ADR-005: Fumadocs for Documentation Portal

Status: Proposed Date: 2026-02-25 Deciders: Platform team

Context

The platform has 40+ markdown documentation files across user guides, developer guides, API reference, and operations docs. These are currently readable only on GitHub or in a code editor. They need to be served as a searchable, navigable documentation portal accessible from the platform UI.

Requirements:

• Serve existing markdown files without rewriting them
• Integrate with the existing Next.js 14 App Router application
• Provide sidebar navigation, full-text search, and responsive layout
• Support the existing docs directory structure (nested folders)
• Minimal configuration and maintenance overhead

Decision

Use Fumadocs (fumadocs-core + fumadocs-ui + fumadocs-mdx) to serve the docs directory at /docs within the existing Next.js application. Fumadocs reads markdown files from the filesystem, generates sidebar navigation from directory structure, and provides built-in search.

Alternatives Considered

1. Nextra

Mature Next.js docs framework. However, Nextra v3 requires Pages Router configuration that conflicts with our App Router setup. The migration path is unclear and Nextra's App Router support is experimental.

2. Docusaurus

React-based docs framework by Meta. Rejected because it's a standalone application — it can't be embedded within an existing Next.js app. Would require a separate deployment, separate domain or subdomain, and duplicate authentication handling.

3. Custom MDX rendering

Build a custom [[...slug]] route with next-mdx-remote or @next/mdx. Provides maximum control but requires building sidebar navigation, search, mobile responsiveness, and table of contents from scratch. Estimated 30-40 hours of work for what Fumadocs provides out of the box.

4. GitBook / ReadMe / external hosted docs

SaaS documentation platforms. Rejected because they can't be embedded within the platform UI, require a separate domain, and create a disconnect between the product and its documentation. Also introduces a recurring cost.

Consequences

Positive:

• Docs are accessible at /docs within the platform — no separate domain or deployment
• Sidebar navigation is auto-generated from directory structure and meta.json files
• Built-in full-text search across all docs
• Supports the existing markdown format without conversion
• Active maintenance and Next.js App Router compatibility
• Dashboard sidebar can link directly to /docs

Negative:

• Adds 3 npm dependencies (fumadocs-core, fumadocs-ui, fumadocs-mdx)
• MDX processing may require next.config.ts modifications
• Fumadocs UI has its own design system that may not perfectly match the platform's existing design
• meta.json files needed in each docs subdirectory for sidebar ordering

Risks:

• Fumadocs is a smaller project than Nextra or Docusaurus — community size and long-term maintenance are less certain. Mitigated by the fact that docs are standard markdown and can be migrated to another framework with minimal effort.
• CSP configuration may need updates to allow Fumadocs assets (fonts, styles).