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,10 +23,21 @@ node_modules/
 .idea/
 .DS_Store
 
-# Ignore build outputs
+# Next.js build outputs
+.next/
+out/
 dist/
 build/
 
+# Next.js cache
+.next/cache/
+
+# Vercel deployment outputs
+.vercel/
+
+# Fumadocs generated files
+.fumadocs/
+
 # Ignore TypeScript compiled outputs
 *.tsbuildinfo
 

.gitignore

@@ -0,0 +1,7 @@
+// @ts-nocheck -- skip type checking
+import * as docs_2 from "../docs/docker-to-iac/index.mdx?collection=docs&hash=1749400994400"
+import * as docs_1 from "../docs/deploystack/index.mdx?collection=docs&hash=1749400994400"
+import * as docs_0 from "../docs/index.mdx?collection=docs&hash=1749400994400"
+import { _runtime } from "fumadocs-mdx"
+import * as _source from "../source.config"
+export const docs = _runtime.docs<typeof _source.docs>([{ info: {"path":"index.mdx","absolutePath":"/Volumes/T9_1/Git/deploy.my/documentation/docs/index.mdx"}, data: docs_0 }, { info: {"path":"deploystack/index.mdx","absolutePath":"/Volumes/T9_1/Git/deploy.my/documentation/docs/deploystack/index.mdx"}, data: docs_1 }, { info: {"path":"docker-to-iac/index.mdx","absolutePath":"/Volumes/T9_1/Git/deploy.my/documentation/docs/docker-to-iac/index.mdx"}, data: docs_2 }], [{"info":{"path":"deploystack/meta.json","absolutePath":"/Volumes/T9_1/Git/deploy.my/documentation/docs/deploystack/meta.json"},"data":{"title":"DeployStack","description":"Documentation for DeployStack","root":true,"icon":"DeployStackLogo"}}, {"info":{"path":"docker-to-iac/meta.json","absolutePath":"/Volumes/T9_1/Git/deploy.my/documentation/docs/docker-to-iac/meta.json"},"data":{"title":"docker-to-iac","description":"docker-to-iac module","root":true,"icon":"Container"}}])

.source/index.ts

@@ -0,0 +1,10 @@
+// source.config.ts
+import { defineDocs } from "fumadocs-mdx/config";
+var docs = defineDocs({
+  // Directory of documents, relative to the project root.
+  // We are using the existing 'docs' folder.
+  dir: "docs"
+});
+export {
+  docs
+};

.source/source.config.mjs

@@ -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,56 @@
+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';
+
+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}>
+      <DocsBody>
+        <h1>{page.data.title}</h1>
+        <MDX />
+      </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);
+
+  return generatePageMetadata({
+    title: page.data.title,
+    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';
+import { CustomNavbar } from '../../lib/components/CustomNavbar';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout
+      {...baseOptions}
+      tree={source.pageTree}
+      nav={{
+        component: <CustomNavbar />,
+      }}
+      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',
+    },
+  });
+}