Documentation System Flow

Overview

Manages the documentation system using Contentlayer and MDX for content management. Provides a structured way to create, organize, and render documentation pages with automatic navigation, table of contents, and static generation.

Main libraries/services:

• contentlayer2 - Content management and static generation
• MDX - Markdown with JSX components
• rehype plugins for code highlighting and linking
• remark plugins for GitHub Flavored Markdown

File Map

📁 contentlayer.config.ts - Contentlayer configuration and document types
📁 config/docs.ts - Documentation navigation and sidebar configuration
📁 app/(docs)/docs/[[...slug]]/page.tsx - Dynamic documentation page renderer
📁 content/docs/ - MDX documentation files
📁 content/guides/ - Guide content files
📁 content/blog/ - Blog post files
📁 content/pages/ - Static page files
📁 components/docs/ - Documentation-specific components
📁 components/content/mdx-components.tsx - MDX component mapping
📁 lib/toc.ts - Table of contents generation

Step-by-Step Flow

Adding New Documentation Section

1. Create new MDX file in content/docs/ directory
2. Add frontmatter with title and description
3. Update config/docs.ts to include new section in sidebar
4. Contentlayer automatically processes the file during build
5. Static routes are generated for the new documentation page

Documentation Page Rendering

1. User navigates to /docs/[slug] URL
2. app/(docs)/docs/[[...slug]]/page.tsx receives slug parameters
3. getDocFromParams finds matching document from allDocs
4. If document exists:
   • Metadata is generated for SEO
   • Table of contents is extracted from content
   • Images are processed with blur data URLs
   • MDX content is rendered with custom components
5. Page is rendered with navigation and TOC sidebar

Content Processing Pipeline

1. Contentlayer scans content/ directory for MDX files
2. Files are processed based on document type (Doc, Guide, Post, Page)
3. Frontmatter is parsed and validated
4. MDX content is transformed with plugins:
   • remarkGfm for GitHub Flavored Markdown
   • rehypeSlug for heading IDs
   • rehypePrettyCode for syntax highlighting
   • rehypeAutolinkHeadings for heading links
5. Static routes are generated for all documents

Navigation and Sidebar

1. config/docs.ts defines navigation structure
2. Sidebar items are organized by categories
3. Each item links to corresponding documentation page
4. Active page highlighting based on current route
5. Breadcrumb navigation for deep linking

Data Flow Diagram

[MDX Files] → [Contentlayer] → [Document Processing] → [Static Generation] → [Next.js Routes]
     ↓
[User Request] → [Dynamic Route] → [Document Lookup] → [MDX Rendering] → [Page Display]
     ↓
[Navigation Config] → [Sidebar Generation] → [Active State] → [User Interface]

Document Types

Doc (Documentation)

{
  title: string (required)
  description?: string
  published?: boolean (default: true)
}

Guide

{
  title: string (required)
  description?: string
  date: string (required)
  published?: boolean (default: true)
  featured?: boolean (default: false)
}

Post (Blog)

{
  title: string (required)
  description?: string
  date: string (required)
  published?: boolean (default: true)
  image: string (required)
  authors: string[] (required)
  categories: ("news" | "education")[] (required)
  related?: string[]
}

Page (Static)

{
  title: string (required)
  description?: string
}

MDX Features

Custom Components

• <Callout> - Alert boxes with different types
• <Steps> - Step-by-step instructions
• Custom HTML element overrides
• Tailwind CSS styling support

Code Highlighting

• Syntax highlighting with rehype-pretty-code
• GitHub Dark theme
• Copy-to-clipboard functionality
• Line number support

Navigation Features

• Automatic heading links
• Table of contents generation
• Previous/Next page navigation
• Breadcrumb support

Configuration Structure

Sidebar Navigation

sidebarNav: [
  {
    title: "Category Name",
    items: [
      {
        title: "Page Title",
        href: "/docs/page-slug",
      },
    ],
  },
];

Main Navigation

mainNav: [
  {
    title: "Documentation",
    href: "/docs",
  },
  {
    title: "Guides",
    href: "/guides",
  },
];

Notes and TODOs

• ✅ Contentlayer integration with MDX processing
• ✅ Automatic static generation for all content
• ✅ Custom components and styling support
• ✅ Table of contents and navigation
• ✅ SEO metadata generation
• ✅ Code syntax highlighting
• ⚠️ Current flows section only has placeholder content
• 🔄 Add search functionality for documentation
• 🔄 Implement documentation versioning
• 🔄 Add documentation analytics
• 🔄 Create documentation templates
• 🔄 Add multi-language support
• 🔄 Implement documentation feedback system