Docs App Development Guide

Next.js documentation site built with Fumadocs, serving as the source of truth for Artifacts platform documentation. Content is accessible to both human developers (via web UI) and LLM agents (via file reads and /llms-full.txt endpoint).

Architecture

apps/docs/
├── content/docs/           # MDX/Markdown documentation source
│   ├── agent-docs/         # Symlinked to .agents/docs (LLM agent instructions)
│   ├── agent-memory/       # Generated: CLAUDE.md/AGENTS.md as MDX (via pnpm generate:docs)
│   ├── planning/           # Feature planning documents
│   └── universal-app/      # Universal app design specs
├── src/
│   ├── app/
│   │   ├── (docs)/         # Documentation route group
│   │   ├── api/search/     # Orama search endpoint
│   │   ├── og/[...slug]/   # OpenGraph image generation
│   │   └── llms-full.txt/  # LLM-friendly plain text export
│   ├── components/mdx/     # Custom MDX components (Mermaid)
│   └── lib/
│       ├── source.ts       # Content source adapter
│       └── layout.shared.tsx
└── source.config.ts        # Fumadocs MDX configuration

Key Patterns

Content Source

All documentation is processed through lib/source.ts:

// source.config.ts - MDX processing with Mermaid support
export const docs = defineDocs({
  dir: 'content/docs',
  docs: {
    schema: frontmatterSchema,
    postprocess: { includeProcessedMarkdown: true }, // Enables getLLMText()
  },
});

// lib/source.ts - Content access
export const source = loader({
  baseUrl: '/',
  source: docs.toFumadocsSource(),
  plugins: [lucideIconsPlugin()],
});

Navigation is controlled by meta.json files in each content directory:

{
  "title": "Section Title",
  "pages": [
    "page-name",
    "---Separator---",
    "another-page"
  ]
}

LLM Text Export

The /llms-full.txt route provides all documentation as plain text for LLM consumption:

// Concatenates all pages with processed markdown
export async function GET() {
  const scan = source.getPages().map(getLLMText);
  return new Response((await Promise.all(scan)).join('\n\n'));
}

Custom MDX Components

Extend getMDXComponents() in mdx-components.tsx to add custom components:

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    Mermaid, // Client-side Mermaid diagram rendering
    ...components,
  };
}

Common Tasks

Adding Documentation

Create .md or .mdx file in content/docs/
Add frontmatter: title (required), description (optional)
Update parent meta.json to include page in navigation
Run pnpm dev to preview at localhost:3125

Adding New MDX Components

Create component in src/components/mdx/
For client-side only components, use 'use client' directive
Register in getMDXComponents() in mdx-components.tsx
Use in MDX files: <ComponentName prop="value" />

OpenGraph Images

Auto-generated for each page via /og/[...slug]/route.tsx. Uses Fumadocs default template with page title and description.

Generated Content

The content/docs/agent-memory/ directory is auto-generated by pnpm generate:docs. It contains MDX versions of all CLAUDE.md and AGENTS.md files with proper frontmatter for Fumadocs rendering.

Do NOT edit files in agent-memory/ directly - they are regenerated from ALL-AGENTS.md templates.

Constraints

Content directory: MUST be content/docs/ (configured in source.config.ts)
Base URL: Docs served from root / (not /docs)
Search: Uses Orama (client-side), language set to English
Mermaid: Requires client-side rendering, cached per theme
agent-memory/: Generated content, do not edit manually

CLAUDE