Skip to content

MkDocs Material as Site Generator

Context

The guide is authored in Markdown and MUST be published as a browsable static site so that engineers can search, link, and skim chapters without cloning the repository. The publication tool sits on the critical path: its admonition syntax, extension model, theme features, and CI footprint all bleed into every chapter file and into the contributor workflow.

Several mature static-site generators exist for Markdown-first documentation: MkDocs Material (Python, Jinja-templated, plugin-rich); Docusaurus (React-based, MDX-first); Hugo (Go, fastest, smaller extension ecosystem for docs); and proprietary surfaces such as Confluence or a hosted wiki. The choice MUST optimise for: (a) admonition support so that "Reference Implementation" callouts render distinctly from prose; (b) diagram-as-code support (Mermaid) without external services; (c) a forkable open-source theme so adopting orgs MAY rebrand cleanly; and (d) a --strict build mode that fails CI when nav targets or references break.

MkDocs Material meets all four criteria out of the box. Its admonition extension (pymdownx.details plus core admonition) is the de-facto standard for typed callouts in Markdown documentation; its superfences extension hosts Mermaid as a custom fence; its Apache-2.0 license matches this guide's license; and mkdocs build --strict is the canonical CI gate in its ecosystem. Docusaurus and Hugo were considered and rejected for reasons documented below.

Decision Drivers

  • The site MUST render typed admonition callouts (e.g., !!! example "Reference Implementation: Pioneer") distinctly from body prose.
  • The site MUST render Mermaid diagrams from code fences without depending on an external rendering service.
  • The site SHOULD build under a --strict mode that fails on broken nav targets or dangling references.
  • The site MUST be installable from a requirements.txt so that CI and contributors share a reproducible toolchain.
  • The theme SHOULD be permissively licensed (Apache-2.0 or MIT) so that adopting orgs MAY rebrand and redistribute.
  • Contributors SHOULD NOT need a JavaScript build toolchain to author or preview chapters locally.

Considered Options

  • MkDocs Material (Python, Apache-2.0)
  • Docusaurus (React/MDX, MIT)
  • Hugo (Go, Apache-2.0) with a docs theme such as Doks or Hugo Book
  • Confluence or hosted wiki (proprietary, SaaS)

Decision Outcome

Chosen option: "MkDocs Material", because it is the only option that satisfies every decision driver simultaneously. Admonitions, Mermaid via superfences, --strict builds, and Apache-2.0 licensing are all first-class. The Python toolchain is a single pip install -r requirements.txt away on every developer machine and in every CI runner. Adopting orgs MAY fork the repository, change the theme palette in mkdocs.yml, and republish without rewriting any chapter content.

Positive Consequences

  • Contributors MAY author chapters in plain Markdown with no JavaScript toolchain.
  • The CI pipeline MAY enforce link integrity by running mkdocs build --strict.
  • Adopting orgs MAY rebrand the site by editing only mkdocs.yml.

Negative Consequences

  • The site is locked to the MkDocs Material theme's visual idiom; a significant visual departure (e.g., a fully bespoke layout) would require either a new theme or a different generator entirely.
  • Custom plugins MUST be authored in Python, which narrows the contributor pool relative to a JavaScript-based stack.

Consequences

After this decision, every chapter file MUST be valid Markdown that renders cleanly under MkDocs Material with the extensions enabled in mkdocs.yml (admonition, pymdownx.details, pymdownx.superfences with Mermaid, pymdownx.tabbed, pymdownx.highlight, pymdownx.inlinehilite). The requirements.txt file pins the MkDocs Material version and its extension dependencies; the version pin is treated as a snapshot per ADR 0004. The CI workflow MUST invoke mkdocs build --strict, and broken nav or dangling links MUST fail the build.

Pros and Cons of the Options

MkDocs Material (Python, Apache-2.0)

A documentation theme for MkDocs with first-class admonition, Mermaid via superfences, search, navigation, and an extensive pymdownx extension stack.

  • Good, because admonitions, Mermaid, and strict-mode builds are all first-class.
  • Good, because the entire toolchain installs from a single requirements.txt.
  • Good, because the Apache-2.0 license matches this guide's license.
  • Bad, because the visual idiom is recognisable and not trivial to depart from.

Docusaurus (React/MDX, MIT)

A React-based static site generator that authors content as MDX (Markdown plus JSX).

  • Good, because MDX lets authors embed React components inline.
  • Good, because the search and versioning features are mature.
  • Bad, because contributors MUST install and maintain a Node.js toolchain.
  • Bad, because MDX-flavoured Markdown is not as portable as standard CommonMark; forks that want to migrate away later face conversion cost.

Hugo with a docs theme

A Go-based static site generator with a wide theme ecosystem.

  • Good, because the build is extremely fast.
  • Good, because the toolchain is a single binary.
  • Bad, because admonition and Mermaid support varies by theme and is not uniformly first-class.
  • Bad, because the docs-theme ecosystem is fragmented; no single theme has the same "default-correct" posture as MkDocs Material.

Confluence or hosted wiki

A proprietary SaaS publication surface.

  • Good, because authoring requires no tooling beyond a web browser.
  • Bad, because the artifact is not forkable — adopting orgs cannot take a copy and republish under their own brand.
  • Bad, because the SaaS lock-in violates the "living, portable artifact" driver.