feat: enhance documentation structure and metadata extraction for improved navigation and title accuracy

Author: Lasim

.source/index.ts

@@ -1,7 +1,8 @@
 // @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 * as docs_3 from "../docs/docker-to-iac/limitations.mdx?collection=docs&hash=1749491540000"
+import * as docs_2 from "../docs/docker-to-iac/index.mdx?collection=docs&hash=1749491540000"
+import * as docs_1 from "../docs/deploystack/index.mdx?collection=docs&hash=1749491540000"
+import * as docs_0 from "../docs/index.mdx?collection=docs&hash=1749491540000"
 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"}}])
+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":"docker-to-iac/limitations.mdx","absolutePath":"/Volumes/T9_1/Git/deploy.my/documentation/docs/docker-to-iac/limitations.mdx"}, data: docs_3 }], [{"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/source.config.mjs

@@ -1,9 +1,15 @@
 // source.config.ts
-import { defineDocs } from "fumadocs-mdx/config";
+import { defineDocs, frontmatterSchema } from "fumadocs-mdx/config";
+import { z } from "zod";
 var docs = defineDocs({
   // Directory of documents, relative to the project root.
   // We are using the existing 'docs' folder.
-  dir: "docs"
+  dir: "docs",
+  docs: {
+    schema: frontmatterSchema.extend({
+      sidebar: z.string().optional()
+    })
+  }
 });
 export {
   docs

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

@@ -4,6 +4,8 @@ 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';
 
 export default async function Page({
   params,
@@ -23,7 +25,6 @@ export default async function Page({
     <DocsPage toc={page.data.toc} full={page.data.full}>
       <CustomNavbar />
       <DocsBody>
-        <h1>{page.data.title}</h1>
         <MDX />
       </DocsBody>
     </DocsPage>
@@ -49,8 +50,22 @@ export async function generateMetadata({
   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 = `/Volumes/T9_1/Git/deploy.my/documentation/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: page.data.title,
+    title: finalTitle,
     description: page.data.description || 'DeployStack Documentation and API Reference',
     slug: slugString,
     url,

docs/docker-to-iac/index.mdx

@@ -1,7 +1,7 @@
 ---
-title: Docker to IaC
+title: Docker to Infrastructure 2
 description: Introduction to the node module docker-to-iac which allows you to transfer docker-compose into IaC templates
-menuTitle: Docker-to-IaC
+sidebar: lol text
 ---
 
 # Docker to Infrastructure as Code Module

docs/docker-to-iac/limitations.mdx

@@ -0,0 +1,89 @@
+---
+title: Limitations
+description: Current limitations and constraints of the docker-to-iac module
+---
+
+# Limitations for docker-to-iac module
+
+## Registry Support
+
+The module currently supports Docker images from -> please check [Supported Registries for docker-to-iac module](/docs/docker-to-iac/supported-registries.md)
+
+## Docker Image Requirement
+
+The `docker-to-iac` module is designed to work exclusively with pre-built Docker images. This means that each service in your `docker-compose.yml` file must specify an `image` property.
+
+## Volume Support
+
+When working with volume mappings in your Docker configuration, be aware that volume support varies among cloud providers:
+
+- Some providers fully support multiple volume mappings
+- Some providers only support the first volume mapping defined in your configuration
+- Some providers support ephemeral files only, meaning no persistent volume storage is available
+- Volume mapping implementation details can differ between providers
+
+Please check the specific provider's documentation to understand their volume mapping capabilities and limitations before deployment.
+
+For example, if your Docker configuration includes multiple volumes:
+
+```yaml
+services:
+  app:
+    image: nginx:latest
+    volumes:
+      - ./config:/etc/nginx/conf.d
+      - ./logs:/var/log/nginx
+      - ./data:/usr/share/nginx/html
+```
+
+Depending on your chosen provider:
+
+- All volume mappings might be supported
+- Only the first volume mapping (`./config:/etc/nginx/conf.d`) might be implemented
+- No volumes might be supported, with only ephemeral storage available
+
+We recommend reviewing your target provider's documentation for detailed information about their volume support capabilities.
+
+### Build Instructions Not Supported
+
+The module does not support services that use the `build` directive. For example:
+
+```yaml [docker-compose.yml]
+# ❌ Not Supported
+services:
+  app:
+    build:
+      context: ./build/app
+      dockerfile: Dockerfile
+```
+
+Instead, you must use pre-built images:
+
+```yaml [docker-compose.yml]
+# ✅ Supported
+services:
+  app:
+    image: nginx:latest
+```
+
+#### Rationale
+
+This limitation exists because Infrastructure as Code (IaC) templates require specific, immutable container images to ensure consistent deployments. The infrastructure and the selection of cloud providers for this docker-to-iac module only allow pre-build container images. It is technically not possible to create a build with the preconfigured infrastructure. This is why the pre-build check was built in. This happens also because the scope of this module is only pre-build container.
+
+### Workaround
+
+If you need to use custom Docker images:
+
+Build your Docker images locally or in your CI/CD pipeline
+Push them to a container registry (like Docker Hub, GitHub Container Registry, or AWS ECR)
+Reference the pushed image in your docker-compose file using the image property
+
+For example:
+
+```yaml
+services:
+  app:
+    image: ghcr.io/your-org/your-app:1.0.0
+```
+
+This ensures that your IaC templates will have access to the exact same container image across all deployments.

docs/index.mdx

@@ -1,7 +1,6 @@
 ---
 title: DeployStack Documentation
 description: Welcome to DeployStack documentation. Learn how to automate Docker Compose deployments across cloud providers with Infrastructure as Code templates and one-click deployments.
-menuTitle: DeployStack Documentation
 ---
 
 # DeployStack Documentation

lib/h1-extractor.ts

@@ -0,0 +1,60 @@
+/**
+ * Utility to extract H1 heading from MDX content for use in page titles
+ */
+
+export interface H1ExtractionResult {
+  h1Title: string | null;
+  fallbackTitle: string;
+}
+
+/**
+ * Extracts the first H1 heading from MDX content
+ * Supports both markdown syntax (# Heading) and JSX syntax (<h1>Heading</h1>)
+ */
+export function extractH1FromMDX(content: string): string | null {
+  if (!content) return null;
+
+  // Remove frontmatter first
+  const contentWithoutFrontmatter = content.replace(/^---[\s\S]*?---\n?/, '');
+
+  // Pattern for markdown H1: # Heading
+  const markdownH1Match = contentWithoutFrontmatter.match(/^#\s+(.+)$/m);
+  if (markdownH1Match) {
+    return markdownH1Match[1].trim();
+  }
+
+  // Pattern for JSX H1: <h1>Heading</h1> or <h1 ...>Heading</h1>
+  const jsxH1Match = contentWithoutFrontmatter.match(/<h1[^>]*>([^<]+)<\/h1>/i);
+  if (jsxH1Match) {
+    return jsxH1Match[1].trim();
+  }
+
+  return null;
+}
+
+/**
+ * Gets the best title for a page, preferring H1 over frontmatter title
+ */
+export function getBestPageTitle(
+  mdxContent: string | undefined,
+  frontmatterTitle: string | undefined
+): H1ExtractionResult {
+  const h1Title = mdxContent ? extractH1FromMDX(mdxContent) : null;
+  const fallbackTitle = frontmatterTitle || 'Untitled';
+
+  return {
+    h1Title,
+    fallbackTitle,
+  };
+}
+
+/**
+ * Gets the final title to use, with H1 taking precedence
+ */
+export function getFinalPageTitle(
+  mdxContent: string | undefined,
+  frontmatterTitle: string | undefined
+): string {
+  const { h1Title, fallbackTitle } = getBestPageTitle(mdxContent, frontmatterTitle);
+  return h1Title || fallbackTitle;
+}

lib/source.ts

@@ -17,6 +17,7 @@ export const source = loader({
   // 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) {
@@ -37,11 +38,19 @@ export const source = loader({
     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;
+    },
+  },
+
   // Optional: You can define global MDX components here if not done elsewhere
   // globalMdxComponents: getMDXComponents(),
-
-  // Optional: Configure how slugs are generated
-  // getSlugs: (file) => { ... }
 });
 
 // You might also want to export page tree and other utilities if needed directly

source.config.ts

@@ -1,7 +1,13 @@
-import { defineDocs } from 'fumadocs-mdx/config';
+import { defineDocs, frontmatterSchema } from 'fumadocs-mdx/config';
+import { z } from 'zod';
 
 export const docs = defineDocs({
   // Directory of documents, relative to the project root.
   // We are using the existing 'docs' folder.
   dir: 'docs',
+  docs: {
+    schema: frontmatterSchema.extend({
+      sidebar: z.string().optional(),
+    }),
+  },
 });