Migrate documentation site to Fumadocs with monorepo structure and shared content - #11

Replace the custom @objectdocs/cli documentation tooling with Fumadocs, a modern Next.js-based documentation framework, and restructure it into a proper monorepo architecture under apps/docs/ while keeping documentation content at the root level for sharing.

Changes

Monorepo Structure

• Multi-package Architecture: Moved all Next.js files to apps/docs/ to avoid polluting the root directory
• Workspace Isolation: Documentation site now has its own package.json with isolated dependencies
• Clean Separation: Clear boundary between protocol packages (packages/*) and applications (apps/*)
• Shared Content: Documentation content remains at /content/docs/ (root level) for easy access and sharing across the repository

Core Infrastructure

• Next.js 16 + App Router: Full static site generation for 136 documentation pages
• Fumadocs MDX: Auto-compilation from /content/docs/ (root level) with type-safe collection handling
• Tailwind CSS v4: New CSS architecture with @tailwindcss/postcss

Directory Structure

Repository Root:
├── content/docs/     # Documentation content (MDX files) - SHARED LOCATION
│   ├── concepts/
│   ├── references/
│   └── specifications/
└── apps/docs/
    ├── app/              # Next.js App Router
    ├── source.config.ts  # Fumadocs collection config (references ../../content/docs)
    ├── next.config.mjs   # Next.js configuration
    ├── tailwind.config.js
    ├── postcss.config.mjs
    ├── tsconfig.json
    └── package.json      # Isolated dependencies

Configuration

// apps/docs/source.config.ts - Collection definition
export const docs = defineDocs({
  dir: '../../content/docs',  // References root-level content
}) as any; // Workaround for pnpm zod@4 type portability

// apps/docs/app/source.ts - Loader setup
import { docs } from 'fumadocs-mdx:collections/server';
export const source = loader({
  baseUrl: '/docs',
  source: (docs as any).toFumadocsSource(),
});

UI Components

• Collapsible sidebar with auto-generated navigation from meta.json files
• Search (⌘K), theme toggle, GitHub integration
• MDX components (Callout, Card, Cards) rendered via fumadocs-ui/mdx

Build Output

Route (app)
├ ○ /
└ ● /docs/[[...slug]] (136 pages)
  ├ /docs
  ├ /docs/concepts/*
  ├ /docs/references/*
  └ /docs/specifications/*

Workspace Configuration

• Updated pnpm-workspace.yaml to include apps/*
• Root package.json scripts use workspace filters: pnpm --filter @objectstack/docs
• Root package.json includes shared dependencies (lucide-react) used by MDX files
• Root tsconfig.json excludes apps directory
• .gitignore updated for apps structure

Screenshot

Scripts

Scripts remain the same from repository root:

pnpm docs:dev    # Start development server
pnpm docs:build  # Build for production
pnpm docs:start  # Start production server

Benefits

1. Clean Root Directory: No Next.js files in repository root
2. Shared Content: Documentation content at /content/docs/ accessible to other tools and workflows
3. Workspace Isolation: Each app/package manages its own dependencies
4. Scalability: Easy to add more apps (e.g., apps/playground, apps/studio)
5. Standard Pattern: Follows Turborepo/Nx monorepo conventions
6. Maintainability: Clear separation of concerns

All existing MDX content preserved at the root level. The .source/ directory (auto-generated by Fumadocs) is gitignored.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.