Skip to content

ADR 005 — MkDocs Material for the documentation site

Status: Accepted Date: 2026-05-09

Context

Plan 104 stands up docs.secruna.com — a public documentation site covering the platform's architecture, feature set, regulatory frameworks, ADRs, and roadmap. The site needs to:

  • Render Markdown content with code highlighting and Mermaid diagrams.
  • Present a clean side navigation with grouped sections.
  • Build deterministically from CI without bespoke tooling.
  • Be cheap to host (a static-site bundle behind any CDN).
  • Match the calm, plain visual register of the marketing site rather than introducing a new design language.

The candidate stacks were:

  1. MkDocs Material — Python, mature, instant search, nav auto-generated from mkdocs.yml, zero JS for content.
  2. Docusaurus — React, used by Meta, plugin ecosystem, versioned docs out of the box.
  3. Astro Starlight — modern, fast, clean defaults; new project to maintain alongside the Next.js marketing site.
  4. Hand-rolled Next.js MDX — reuses the marketing-site stack; no new tool to learn but every feature is bespoke.

Decision

Use MkDocs Material.

The deciding factors:

  • Stack consistency with cp-api. The control-plane API is Python (FastAPI, Pydantic v2). Picking a Python doc tool means the same uv workflow and the same Python version assumption apply. Engineers already work in this toolchain daily.
  • Content-first, zero-JS rendering. MkDocs produces static HTML with minimal JavaScript. The marketing site (Next.js) is marketing's job; documentation should not need a hydration step to be readable.
  • Instant search shipped in the default install. No Algolia integration, no separate index build, no API keys to manage.
  • Mermaid via pymdownx.superfences. First-class diagram support without additional plugins or build steps.
  • Mature. MkDocs has been stable for a decade; Material is the most-deployed theme by a wide margin. Predictable behaviour under upgrade is worth more than novelty.

Consequences

Positive

  • A single mkdocs build --strict command produces the entire site, asserts no broken internal links, and exits non-zero on any failure. The Dockerfile (multi-stage build → nginx:alpine) is roughly 30 lines.
  • Editors writing content only need a Markdown file and a nav entry. No frontmatter ceremony, no JSX islands, no MDX import boilerplate.
  • The roadmap and versions pages are produced by a small Bash script (scripts/sync-docs.sh) that runs before the build — no plugin authoring needed.

Negative

  • Adding interactive components (e.g. an embedded API explorer in Phase 4) is harder than in a React-based stack. We will most likely solve this by linking out to a separately-hosted Swagger UI rather than embedding one.
  • The Material theme palette and feature set are opinionated. Heavy customisation pulls us into theme overrides, which are more brittle than a fully-bespoke React component tree would be.
  • Python tooling is a new dependency for any contributor whose primary stack is the Next.js frontend or marketing site. The build is uv sync && bash scripts/sync-docs.sh && mkdocs build --strict, but it is more friction than pnpm build.