Merge pull request #137 from deploystackio/main

migration to fumadocs

Author: Lasim

.github/workflows/deploy_prod.yml .github/workflows/_deploy_prod.yml_.github/workflows/deploy_prod.yml renamed to .github/workflows/_deploy_prod.yml_

@@ -36,6 +36,9 @@ jobs:
       - name: Run Lint Links
         run: npm run lint:links
 
+      - name: Run Lint Links
+        run: npm run build        
+
   release:
     name: Run Release
     runs-on: ubuntu-latest

.github/workflows/ci.yml

@@ -23,9 +23,19 @@ node_modules/
 .idea/
 .DS_Store
 
-# Ignore build outputs
-dist/
-build/
+# outputs
+.turbo
+.next
+dist
+.contentlayer
+.eslintcache
+.source
+
+# Next.js cache
+.next/cache/
+
+# Fumadocs generated files
+.fumadocs/
 
 # Ignore TypeScript compiled outputs
 *.tsbuildinfo
@@ -59,3 +69,6 @@ ehthumbs.db
 # Tests
 coverage/
 .jest/
+
+._*.mdx
+._*.ts

.gitignore

@@ -1,97 +1,122 @@
 # DeployStack Documentation
 
-This repository contains the official documentation for the DeployStack ecosystem. Visit [deploystack.io](https://deploystack.io) to learn more about our platform.
+This repository contains the official documentation site for the [DeployStack](https://deploystack.io/docs/) ecosystem, built with [fumadocs](https://fumadocs.vercel.app/). Visit [deploystack.io](https://deploystack.io) to learn more about our platform.
 
-## Project Structure
+## Technology Stack
+
+- **Framework**: Next.js 15 with App Router
+- **Documentation**: Fumadocs for modern docs experience
+- **Content**: MDX (Markdown + React components)
+- **Styling**: Tailwind CSS
+- **Language**: TypeScript
 
-Key directories in this repository:
+## Project Structure
 
 ```text
 .
-├── docs/
-│   ├── assets/
-│   │   └── images/
-│   ├── deploystack/
-│   ├── docker-to-iac/
-│   └── sidebar-links.json
-└── markdown-rules/
+├── docs/                  # Documentation content (MDX files)
+│   ├── deploystack/       # DeployStack documentation
+│   ├── docker-to-iac/     # Docker-to-IaC documentation
+│   └── assets/            # Images and static assets
+├── app/                   # Next.js app directory (fumadocs framework)
+├── lib/                   # Documentation utilities & components
+└── source.config.ts       # Fumadocs configuration
+```
+
+**Note**: The `app/` directory contains the fumadocs framework setup and should not be modified for content changes. All documentation content goes in the `docs/` directory.
+
+## Development Setup
+
+```bash
+# Install dependencies
+npm ci
+
+# Start documentation development server (http://localhost:3000)
+npm run dev
+
+# Build documentation site for production
+npm run build
+
+# Start production server
+npm run start
+
+# Validate documentation quality
+npm run lint:md      # Markdown linting
+npm run lint:links   # Link validation
 ```
 
 ## Contributing Guidelines
 
-### Documentation Standards
+### Writing Documentation
 
-1. Store all documentation files in the `./docs` directory
-2. Place images in `./docs/assets/images`
-3. Use absolute links for all references:
-   - Documentation: `/docs/docker-to-iac/index.md`
+1. **Content Format**: Write all documentation in MDX format (`.mdx` files)
+2. **Location**: Store all content in the `docs/` directory
+3. **Navigation**: Use `meta.json` files in each directory to control navigation structure
+4. **Assets**: Place images in `docs/assets/images/` with appropriate subdirectories
+5. **Links**: Use absolute paths for all references:
+   - Documentation: `/docs/docker-to-iac/`
    - Images: `/docs/assets/images/example.png`
 
-### Adding New Content
+### Navigation Structure
 
-When creating new documentation:
+Fumadocs automatically generates navigation from your file structure and `meta.json` files:
 
-1. Add new pages to the appropriate subdirectory in `./docs`
-2. Follow the established file naming conventions
-3. Ensure all links are absolute paths
-4. Include necessary sidebar entries in `sidebar-links.json`
+- Each directory can have a `meta.json` file to configure its appearance in navigation
+- File-based routing: `docs/deploystack/index.mdx` becomes `/docs/deploystack`
+- Nested directories create hierarchical navigation
 
-### Asset Management
+### Adding New Content
 
-For diagrams and architectural images (optional):
+1. Create new `.mdx` files in the appropriate `docs/` subdirectory
+2. Add or update `meta.json` files to control navigation
+3. Follow established naming conventions
+4. Ensure all links use absolute paths
+5. Test locally with `npm run dev`
 
-1. Use [draw.io](https://app.diagrams.net/) for creating diagrams
-2. Export as PNG with included diagram data for future editing
-3. Place files in the appropriate subdirectory under `./docs/assets/images`
+### Asset Management
 
-If you want to upload images, please minify them.
+For diagrams and images:
+
+1. Use [drow.io](https://app.diagrams.net/) for creating diagrams
+2. Export as PNG or WebP format
+3. Optimize images for web (compress file sizes)
+4. Place files in appropriate subdirectories under `docs/assets/images/`
 
 ## Deployment Process
 
-Our deployment process uses two main branches:
+Our deployment uses a two-branch workflow:
 
-- `main`: Development branch
-- `prod`: Production branch
+- **`main`**: Development branch for content updates and testing
+- **`prod`**: Production branch that deploys to [deploystack.io/docs](https://deploystack.io/docs)
 
 ### Workflow
 
 1. Create feature branches from `main`
 2. Submit pull requests to `main`
 3. After approval and merge to `main`, changes are automatically validated
-4. Merge to `prod` to deploy to [deploystack.io/docs](https://deploystack.io/docs)
+4. Merge to `prod` to deploy to production
 
 ### Continuous Integration
 
 The CI pipeline includes:
 
-- Markdown linting
-- Link validation
-- Automatic versioning using semantic release
+- Markdown linting and validation
+- Link checking to prevent broken links
+- Automatic fumadocs build verification
 - Production deployment triggers
 
-## Development Setup
-
-```bash
-# Install dependencies
-npm ci
-
-# Run markdown linting
-npm run lint:md
-
-# Check for dead links
-npm run lint:links
-```
-
-## Release Process
+## Local Development
 
-Releases are managed automatically through our CI/CD pipeline. When merging to the production branch:
+When running `npm run dev`, the documentation site will be available at `http://localhost:3000`. The fumadocs framework provides:
 
-1. Changes are validated
-2. Documentation is built
-3. Content is deployed to [deploystack.io/docs](https://deploystack.io/docs)
+- Hot reloading for content changes
+- Automatic navigation generation
+- Built-in search functionality
+- Responsive design
+- Dark/light mode support
 
 ## 💬 Need Help?
 
 - 📚 Check our [Documentation](https://deploystack.io/docs)
 - 🎯 Report issues on [GitHub](https://github.com/deploystackio/documentation/issues)
-- 📧 Use Discord to chat with us at [https://discord.gg/UjFWwByB](https://discord.gg/UjFWwByB)
+- 📧 Join our Discord at [https://discord.gg/UjFWwByB](https://discord.gg/UjFWwByB)

README.md

@@ -0,0 +1,4 @@
+import { source } from '../../../lib/source';
+import { createFromSource } from 'fumadocs-core/search/server';
+
+export const { GET } = createFromSource(source);

app/api/search/route.ts

@@ -0,0 +1,74 @@
+import type { Metadata } from 'next';
+import { DocsPage, DocsBody } from 'fumadocs-ui/page';
+import { notFound } from 'next/navigation';
+import { source } from '@/lib/source';
+import { generatePageMetadata, getCanonicalUrl } from '@/lib/seo-utils';
+import { CustomNavbar } from '@/lib/components/CustomNavbar';
+import { getFinalPageTitle } from '@/lib/h1-extractor';
+import { readFile } from 'fs/promises';
+import { getMDXComponents } from '@/mdx-components';
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const { slug } = await params;
+  const page = source.getPage(slug);
+
+  if (!page) {
+    notFound();
+  }
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <CustomNavbar />
+      <DocsBody>
+        <MDX components={getMDXComponents()} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>;
+}): Promise<Metadata> {
+  const { slug } = await params;
+  const page = source.getPage(slug);
+
+  if (!page) {
+    return {};
+  }
+
+  const slugString = slug ? slug.join('/') : '';
+  const url = getCanonicalUrl(slugString);
+
+  // Read the raw MDX file to extract H1 heading
+  let finalTitle = page.data.title;
+  try {
+    // Get the absolute path from the page info
+    const filePath = page.file.path;
+    const absolutePath = `./docs/${filePath}`;
+    const rawContent = await readFile(absolutePath, 'utf-8');
+    finalTitle = getFinalPageTitle(rawContent, page.data.title);
+  } catch (error) {
+    // Fallback to frontmatter title if file reading fails
+    console.warn('Failed to read MDX file for H1 extraction:', error);
+    finalTitle = page.data.title;
+  }
+
+  return generatePageMetadata({
+    title: finalTitle,
+    description: page.data.description || 'DeployStack Documentation and API Reference',
+    slug: slugString,
+    url,
+  });
+}

app/docs/[[...slug]]/page.tsx

@@ -0,0 +1,22 @@
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { ReactNode } from 'react';
+import { baseOptions } from '../layout.config';
+import { source } from '../../lib/source';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout
+      {...baseOptions}
+      tree={source.pageTree}
+      nav={{
+        title: 'DeployStack Docs',
+        url: '/docs',
+      }}
+      sidebar={{
+        defaultOpenLevel: 1
+      }}
+    >
+      {children}
+    </DocsLayout>
+  );
+}

app/docs/layout.tsx

@@ -0,0 +1,27 @@
+import { source } from '@/lib/source';
+import { getCanonicalUrl } from '@/lib/seo-utils';
+
+export async function GET() {
+  const pages = source.getPages();
+  
+  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${pages
+  .map((page) => {
+    const url = getCanonicalUrl(page.url);
+    return `  <url>
+    <loc>${url}</loc>
+    <lastmod>${new Date().toISOString()}</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>`;
+  })
+  .join('\n')}
+</urlset>`;
+
+  return new Response(sitemap, {
+    headers: {
+      'Content-Type': 'application/xml',
+    },
+  });
+}

app/docs/sitemap.xml/route.ts

@@ -0,0 +1,38 @@
+/* Import Fumadocs UI complete styles */
+@import 'fumadocs-ui/css/style.css';
+
+/* Custom navbar styling to match main site */
+/* Navbar height override removed since navbar is now inside content area */
+
+/* Ensure logo and navigation styling matches main site */
+.fd-nav-title {
+  font-weight: 600;
+  font-size: 18px;
+}
+
+/* Style the login button to match main site */
+[data-fumadocs-nav] a[href*="login"] {
+  background: hsl(var(--primary));
+  color: hsl(var(--primary-foreground));
+  border-radius: 9999px;
+  padding: 0.5rem 1rem;
+  font-weight: 500;
+  transition: background-color 0.2s ease;
+}
+
+[data-fumadocs-nav] a[href*="login"]:hover {
+  background: hsl(var(--primary) / 0.9);
+}
+
+/* Ensure Documentation link is highlighted when active */
+[data-fumadocs-nav] a[href="/docs"][data-active="true"] {
+  color: hsl(var(--primary));
+  font-weight: 600;
+}
+
+/* Optional: Add your own global styles or font imports here */
+/* For example, to set a default font:
+body {
+  font-family: 'Inter', sans-serif; // Make sure to import 'Inter' or your chosen font
+}
+*/

app/global.css

@@ -0,0 +1,12 @@
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+
+export const baseOptions: BaseLayoutProps = {
+  // Navigation bar configuration (now handled by CustomNavbar)
+  nav: {
+    title: 'DeployStack Docs',
+    url: '/docs',
+  },
+
+  // GitHub repository for edit links
+  githubUrl: 'https://github.com/deploystackio/documentation',
+};