Skip to main content

ADR-0005 — Documentation as MDX in the repository

Date2026-08-17
Superseded by—

Context​

The requirement is specific: a wiki and a documentation section covering every decision, with rich content — diagrams, pictures, mockups — cross-linked, in MDX, kept up to date by every change, and deployed.

The failure mode this is guarding against is the usual one. Documentation lives somewhere separate from the code, the code changes, the documentation does not, and within three months the docs are actively misleading — worse than nothing, because people believe them.

Decision​

Documentation is MDX in docs/ at the repository root, rendered by a Docusaurus site in apps/docs, deployed to Cloudflare Pages on every push and every pull request.

  • Content at the root, renderer in apps/. The site is configured with path: '../../docs'. Docs are a first-class part of the repo, browsable on GitHub without the site; apps/docs is only a renderer.
  • MDX, not Markdown. Because "rich" was the requirement: Mermaid diagrams, inline SVG mockups, styled status pills, JSX components where a table will not do.
  • Mermaid via @docusaurus/theme-mermaid, which renders client-side. No headless browser in CI.
  • onBrokenLinks: 'throw', onBrokenAnchors: 'throw'. A stale cross-reference fails the build. Cross-linking is only trustworthy if it is enforced.
  • Mockups as inline SVG, hand-drawn in the MDX. They live in git, they diff, and they cannot drift out of the repo the way a Figma link does.
  • The rule in CLAUDE.md: every change affecting product behaviour, the data model, the API surface, or deployment updates the docs in the same PR.
  • A docs-check workflow that comments on any PR touching code but not docs/. It comments rather than fails, because the author knows better than a path glob whether a change is genuinely documentation-neutral.

Consequences​

What gets harder:

  • Non-technical contribution. Editing documentation means a pull request. That is a real cost and an accepted one — right now everyone who edits these docs also edits code.
  • The docs build is on the critical path. A broken link blocks CI. Intended, occasionally annoying.
  • Docusaurus is a dependency with its own upgrade cycle and its own React version.
  • MDX is not Markdown. Raw HTML in a page must be valid JSX — class becomes className, stroke-width becomes strokeWidth. Pasting HTML from elsewhere fails in confusing ways.

What we are committed to:

  • Docusaurus's routing and sidebar conventions. Moving a page changes its URL, and onBrokenLinks: throw means every inbound link must move with it. Good discipline, real work.
  • Sidebars written by hand in apps/docs/sidebars.ts rather than autogenerated — adding a page means placing it deliberately.

What this creates:

  • Docs deploy to Cloudflare Pages, so PR previews of the documentation come free with ADR-0006.
  • The decision log itself, which is where decisions are recorded once they have been confirmed.

Alternatives considered​

Notion or Confluence​

Best editing experience by a distance, best for non-technical contributors, real database views.

Rejected on the central requirement. Documentation outside the repository cannot be updated in the same pull request as the code, cannot be reviewed alongside a diff, and cannot be enforced by CI. Every wiki that has ever gone stale went stale this way.

The GitHub wiki​

In GitHub, near the code, easy to edit. Rejected because it is a separate git repository — no pull request, no review, no CI, and no way to change it in the same commit as the code. It also cannot render Mermaid or MDX components.

Plain Markdown, no site​

Zero build, renders on GitHub. Rejected on "rich": no Mermaid, no cross-link checking, no navigation, no search, and inline SVG mockups render as nothing.

VitePress, Astro Starlight, or Nextra​

All good. Starlight in particular is lighter than Docusaurus. Chosen Docusaurus for first-party Mermaid support with no extra plugin or headless browser, and for a docs-versioning story we will probably want once the API has external consumers. Not a strong preference; a well-argued swap would be a reasonable ADR.

An ADR CLI (adr-tools, log4brains)​

Purpose-built for decision records. Rejected because it would split documentation across two systems — an ADR tool for decisions and something else for everything else — for the sake of a file-naming convention we can follow by hand.

Open questions​

  • Access control. The docs site is currently public if the Pages project is public. Access restrictions and unpublished commercial decisions may argue for putting it behind Cloudflare Access.
  • Versioning. Docusaurus supports versioned docs. Not enabled; not needed until the API has consumers we do not control.
  • Search. Local search only. Algolia DocSearch when there is enough content to need it.