Skip to main content

ADR-0003: Migrate Documentation from MkDocs to Docusaurus

Status: Accepted
Date: 2026-05-20
Deciders: Gu

Context​

The technical documentation stack was built on MkDocs with the Material theme. MkDocs development has effectively stalled: the core maintainers have shifted focus to MkDocs 2.0, a complete rewrite that is not backwards-compatible with the existing plugin ecosystem — including Material for MkDocs, the most widely used theme. At the time of this decision, MkDocs 2.0 has no stable release and no confirmed timeline.

This creates an unacceptable risk surface for a documentation stack that is intended to be automated and maintained long-term:

  • Upstream uncertainty: relying on a framework whose current version is in maintenance mode and whose successor is still in early development introduces compounding risk as the plugin ecosystem diverges.
  • No fork path: maintaining a private fork of MkDocs to unblock the plugin ecosystem is not viable — it would create permanent maintenance overhead with no upstream to merge from.
  • Plugin fragility: the MkDocs plugin ecosystem (Mermaid pre-rendering, versioning via mike, include-markdown, monorepo) is a chain of third-party packages with no coordinated compatibility guarantee under MkDocs 2.0.

Decision​

Replace MkDocs with Docusaurus as the documentation framework.

Docusaurus is actively maintained by Meta, has a stable release track, a large ecosystem, and is built on React and MDX — the same stack as our frontend. Key capabilities gained:

  • React component embedding: because our frontend is also React, UI components can be imported and rendered directly inside documentation pages. This eliminates the need for screenshots or screen recordings to demonstrate UI behaviour; live, interactive examples can be embedded from production frontend code.
  • Built-in Mermaid support via @docusaurus/theme-mermaid — no custom Python hooks required.
  • Native versioning without an external tool like mike.
  • MDX — Markdown files can use JSX when needed, enabling richer documentation without leaving the docs repo.
  • Cloudflare Pages integration — CF Pages can build Docusaurus directly from the main branch, replacing the docs-site branch + mike deployment pattern with a single merge-to-deploy flow.

Alternatives Considered​

  • Wait for MkDocs 2.0 — ruled out: no stable release, no confirmed timeline, no plugin compatibility guarantees. Blocking documentation automation on an unreleased framework is not acceptable.
  • Fork MkDocs and maintain compatibility — ruled out: permanent maintenance burden with no upstream. Diverts engineering time from product work.
  • Migrate to a different static site generator (Hugo, Astro, VitePress) — considered but ruled out: Docusaurus is the only option with a React-native component model that matches our frontend stack, enabling live UI embedding. The others require a separate toolchain for interactive examples.

Consequences​

  • MkDocs, Material theme, Python virtualenv, and all associated plugins removed from the repository.
  • mike versioning and docs-site branch deployment pattern replaced by Cloudflare Pages direct build from main.
  • All existing Markdown content preserved as-is; only MkDocs-specific syntax (admonitions, icon shortcodes, grid cards) migrated to Docusaurus equivalents.
  • Frontmatter schema extended with relates_to, description, last_verified, and owner fields to support the planned AI agent documentation pipeline (see ADR-0001).
  • Future documentation can embed live React components from the frontend codebase directly in .mdx files.