ADR-014: Migrate Documentation from MkDocs Material to Docusaurus 3

Status: Accepted (supersedes ADR-000 for the documentation site engine)

Date: 2026-03-12

Context

MkDocs Material is entering maintenance mode (v9.7.0 final, Insiders repo deleted May 2026). The current setup has navigation issues at scale — 238 docs produce a wall of links with navigation.expand + toc.integrate. We prototyped both Starlight and Docusaurus with identical 13-page content sets.

Decision

Migrate to Docusaurus 3 with a single docs instance reading from the existing docs/ directory.

Why Docusaurus

• React component model — interactive landing pages, custom components
• Navbar tab navigation — vs sidebar-only (better at scale)
• Multi-instance docs capability — future customer/internal separation
• Infima CSS framework — enterprise look without Tailwind conflicts
• Large ecosystem — 60k+ GitHub stars, active maintenance
• Native dark/light mode toggle

Architecture

sv0-documentation/
├── docs/                        # UNCHANGED — all docs stay here
│   └── */_category_.json        # Sidebar ordering metadata
├── mkdocs.yml                   # Kept as agent nav manifest
├── docusaurus-site/
│   ├── docusaurus.config.ts     # Single instance, path: '../docs'
│   ├── sidebars.ts              # Autogenerated from docs/
│   ├── src/pages/index.tsx      # React landing page
│   ├── src/css/custom.css       # SecurityV0 indigo branding
│   └── static/                  # Logos, favicon

Critical Constraint

The docs/ directory is heavily referenced by all agent tooling (AGENTS.md, CLAUDE.md, greps, reads). It stays in place — no file moves, no renames. Docusaurus reads from docs/ via path: '../docs' in its config.

Plugins

Feature	Plugin
Local search	@easyops-cn/docusaurus-search-local
Wiki-links	@portaljs/remark-wiki-link
Mermaid diagrams	@docusaurus/theme-mermaid
Last updated	Built-in (showLastUpdateTime)
Auto sidebar	Built-in (type: 'autogenerated')

What We Keep

• mkdocs.yml — still referenced in AGENTS.md, README, repo-guide as the nav manifest
• All existing frontmatter — Docusaurus ignores unknown keys (type, status, source, relates-to, priority)
• Customer docs as docs/customer/ subfolder — separate instance when access control needed (future)

Consequences

• CI/CD: Python/MkDocs → Node/Docusaurus build pipeline
• Build artifacts: docusaurus-site/build/ replaces site/
• Navigation: Filesystem-based autogenerated sidebar with _category_.json ordering
• Admonitions: !!!note syntax → :::note syntax (3 occurrences converted)
• Markdown format: format: 'detect' with MDX compatibility disabled to handle angle brackets and curly braces in existing docs
• Tags: parseFrontMatter hook flattens nested YAML tag arrays