docs: enhance documentation structure by adding separate sources for development and self-hosted sections; remove root flags from meta.json files; introduce debug script for loading verification

Author: Lasim

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

@@ -3,7 +3,7 @@ import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 import { HomeLayout } from 'fumadocs-ui/layouts/home';
 import { DocsPage, DocsBody } from 'fumadocs-ui/page';
 import { notFound } from 'next/navigation';
-import { source } from '@/lib/source';
+import { source, mainSource, developmentSource, selfHostedSource } from '@/lib/source';
 import { generatePageMetadata, getCanonicalUrl } from '@/lib/seo-utils';
 import { getFinalPageTitle } from '@/lib/h1-extractor';
 import { readFile } from 'fs/promises';
@@ -41,12 +41,25 @@ export default async function Page({
     );
   }
 
+  // Determine which section we're in and get the appropriate page tree
+  const firstSegment = slug[0];
+  let pageTree = mainSource.pageTree;
+  let navTitle = 'DeployStack Docs';
+  
+  if (firstSegment === 'development') {
+    pageTree = developmentSource.pageTree;
+    navTitle = 'Development Docs';
+  } else if (firstSegment === 'self-hosted') {
+    pageTree = selfHostedSource.pageTree;
+    navTitle = 'Self-Hosted Docs';
+  }
+
   return (
     <DocsLayout
       {...docsOptions}
-      tree={source.pageTree}
+      tree={pageTree}
       nav={{
-        title: 'DeployStack Docs',
+        title: navTitle,
         url: '/',
       }}
       sidebar={{
@@ -63,18 +76,8 @@ export default async function Page({
 }
 
 export async function generateStaticParams() {
-  const params = source.generateParams();
-
-  const result = [
-    ...params,
-    ...docs.docs
-      .filter((page: any) => page._file.flattenedPath)
-      .map((page: any) => ({
-        slug: page._file.flattenedPath.split('/'),
-      })),
-  ];
-
-  return result;
+  // Simply use the unified source generateParams
+  return source.generateParams();
 }
 
 export async function generateMetadata({

docs/development/meta.json

@@ -2,7 +2,6 @@
   "title": "Development",
   "description": "Development documentation for DeployStack",
   "icon": "Code",
-  "root": true,
   "pages": [
     "index",
     "---Sections---",

docs/meta.json

@@ -2,7 +2,6 @@
   "title": "DeployStack",
   "description": "Documentation for DeployStack",
   "icon": "DeployStackLogo",
-  "root": true,
   "pages": [
     "quick-start",
     "---General---",
@@ -20,9 +19,6 @@
     "github-application",
     "github-oauth-setup",
     "troubleshooting",
-    "local-setup",
-    "---Developer Resources---",
-    "development",
-    "self-hosted"
+    "local-setup"
   ]
 }

docs/self-hosted/meta.json

@@ -2,7 +2,6 @@
   "title": "Self Hosted",
   "description": "Self-hosted DeployStack",
   "icon": "DeployStackLogo",
-  "root": true,
   "pages": [
     "..."  
   ]

lib/debug-source.ts

@@ -0,0 +1,26 @@
+// Debug script to see what's being loaded
+import { docs } from '../.source/index';
+
+const allDocs = docs.docs;
+const allMeta = docs.meta;
+
+console.log('=== ALL DOCS ===');
+allDocs.forEach((doc: any) => {
+  console.log('Path:', doc._file.path, 'Flattened:', doc._file.flattenedPath);
+});
+
+console.log('\n=== DEVELOPMENT DOCS ===');
+const developmentDocs = allDocs.filter((doc: any) => 
+  doc._file.path.startsWith('development/')
+);
+developmentDocs.forEach((doc: any) => {
+  console.log('Path:', doc._file.path, 'Flattened:', doc._file.flattenedPath);
+});
+
+console.log('\n=== SELF-HOSTED DOCS ===');
+const selfHostedDocs = allDocs.filter((doc: any) => 
+  doc._file.path.startsWith('self-hosted/')
+);
+selfHostedDocs.forEach((doc: any) => {
+  console.log('Path:', doc._file.path, 'Flattened:', doc._file.flattenedPath);
+});

lib/source.ts

@@ -7,43 +7,128 @@ import { loader } from 'fumadocs-core/source';
 import { icons } from 'lucide-react';
 import { createElement } from 'react';
 import { DeployStackLogo } from './components/DeployStackLogo';
+import { createMDXSource } from 'fumadocs-mdx';
+import type { PageTree } from 'fumadocs-core/server';
 
-export const source = loader({
-  // Base URL for the documentation pages.
-  // Since we've moved docs to the root level, baseUrl should be '/'
-  // This means docs/index.mdx will be at / and other docs at their direct paths
-  baseUrl: '/',
-  // The source of the documents, converted to Fumadocs format.
-  source: docs.toFumadocsSource(),
-  
-  // Icon handler to support both lucide-react icons and custom icons
-  icon(icon) {
-    if (!icon) {
-      return; // No icon specified
-    }
+// Helper function for icon handling
+function createIconHandler() {
+  return (icon?: string) => {
+    if (!icon) return;
 
-    // Handle custom icons
     if (icon === 'DeployStackLogo') {
       return createElement(DeployStackLogo);
     }
 
-    // Handle lucide-react icons
     if (icon in icons) {
       return createElement(icons[icon as keyof typeof icons]);
     }
 
-    // If icon not found, return undefined
     return undefined;
-  },
+  };
+}
 
-  // Customize page tree to support custom sidebar titles
-  pageTree: {
-    attachFile(node, file) {
-      // If the file has a custom sidebar title, use it instead of the title
-      if (file?.data && 'sidebar' in file.data && file.data.sidebar) {
-        node.name = file.data.sidebar as string;
-      }
-      return node;
-    },
-  },
+// Filter docs into separate sections
+const allDocs = docs.docs;
+const allMeta = docs.meta;
+
+// Main docs (root level - exclude development and self-hosted)
+const mainDocs = allDocs.filter((doc: any) => {
+  const path = doc._file.path;
+  return !path.startsWith('development/') && !path.startsWith('self-hosted/');
+});
+
+const mainMeta = allMeta.filter((meta: any) => {
+  const path = meta._file.path;
+  return !path.startsWith('development/') && !path.startsWith('self-hosted/');
+});
+
+// Development docs - keep the full path
+const developmentDocs = allDocs.filter((doc: any) => 
+  doc._file.path.startsWith('development/')
+);
+
+const developmentMeta = allMeta.filter((meta: any) => 
+  meta._file.path.startsWith('development/')
+);
+
+// Self-hosted docs - keep the full path
+const selfHostedDocs = allDocs.filter((doc: any) => 
+  doc._file.path.startsWith('self-hosted/')
+);
+
+const selfHostedMeta = allMeta.filter((meta: any) => 
+  meta._file.path.startsWith('self-hosted/')
+);
+
+// Create separate sources for each section
+export const mainSource = loader({
+  baseUrl: '/',
+  source: createMDXSource(mainDocs, mainMeta),
+  icon: createIconHandler(),
+});
+
+// For development and self-hosted, we keep the full path structure
+export const developmentSource = loader({
+  baseUrl: '/',  // Changed from '/development' to '/'
+  source: createMDXSource(developmentDocs, developmentMeta),
+  icon: createIconHandler(),
 });
+
+export const selfHostedSource = loader({
+  baseUrl: '/',  // Changed from '/self-hosted' to '/'
+  source: createMDXSource(selfHostedDocs, selfHostedMeta),
+  icon: createIconHandler(),
+});
+
+// Unified source for backward compatibility and dynamic usage
+export const source = {
+  getPage(slug?: string[], locale?: string) {
+    if (!slug || slug.length === 0) return mainSource.getPage(slug, locale);
+    
+    const firstSegment = slug[0];
+    
+    // For development section, use the full slug path
+    if (firstSegment === 'development') {
+      return developmentSource.getPage(slug, locale);
+    }
+    
+    // For self-hosted section, use the full slug path
+    if (firstSegment === 'self-hosted') {
+      return selfHostedSource.getPage(slug, locale);
+    }
+    
+    // For main docs, use as-is
+    return mainSource.getPage(slug, locale);
+  },
+  
+  getPages(locale?: string) {
+    return [
+      ...mainSource.getPages(locale),
+      ...developmentSource.getPages(locale),
+      ...selfHostedSource.getPages(locale),
+    ];
+  },
+  
+  generateParams() {
+    // Get params from all sources
+    const mainParams = mainSource.generateParams();
+    const devParams = developmentSource.generateParams();
+    const selfParams = selfHostedSource.generateParams();
+    
+    return [
+      ...mainParams,
+      ...devParams,
+      ...selfParams,
+    ];
+  },
+  
+  // Get appropriate page tree based on current path
+  getPageTree(path?: string) {
+    if (path?.startsWith('/development')) return developmentSource.pageTree;
+    if (path?.startsWith('/self-hosted')) return selfHostedSource.pageTree;
+    return mainSource.pageTree;
+  },
+  
+  // Default page tree for compatibility
+  pageTree: mainSource.pageTree,
+};