Skip to content

Documentation Tooling

The state of the documentation generator ecosystem matters for this project because we're building docs to last years.

The current situation (May 2026)

The MkDocs ecosystem fractured in early 2026:

  • MkDocs 1.x — the version most teams use today — is no longer maintained. Its sole maintainer stepped down. Security fixes only.
  • MkDocs 2.0 — a ground-up rewrite — broke compatibility with Material for MkDocs and the entire plugin ecosystem. It has a closed contribution model and ships without a clear licence. Not viable.
  • Material for MkDocs — the theme our config uses — committed to security-only support for 12 months from Feb 2026 (i.e. through approximately Feb 2027), then end-of-life.
  • Zensical — the official successor, built by the same team behind Material for MkDocs. Same config format, same theme philosophy, MIT licensed, actively developed.
  • ProperDocs — a community fork of MkDocs 1.x that maintains plugin compatibility. A reasonable bridge if Zensical isn't ready.

Our choice: Zensical

We use Zensical as the primary documentation generator because:

  1. It's built by the team behind the visual style this config uses
  2. It's actively developed under a normal open source licence (MIT)
  3. The config format is largely compatible with our existing mkdocs.yml
  4. A migration tool exists from Material for MkDocs projects
  5. It's faster than MkDocs (Rust core with differential builds)

When to revisit

We should revisit this choice if any of:

  • Zensical's plugin ecosystem stalls
  • A clearer winner emerges in the static site generator space
  • Our needs outgrow it (e.g. we need very deep API doc integration)

Setup

pip install zensical
zensical serve        # local preview at http://localhost:8000
zensical build          # build static site to ./site/

pip install -r requirements.txt
mkdocs serve
mkdocs build

The mkdocs.yml config in this repo works with both — Zensical is designed for compatibility.

CI deployment

Our GitHub Actions workflow uses Zensical with a fallback to MkDocs Material. See .github/workflows/docs-deploy.yml.

Avoiding lock-in

We deliberately:

  • Use plain Markdown — no proprietary syntax
  • Use standard front matter
  • Avoid plugins that aren't supported by both Zensical and MkDocs Material
  • Keep our overrides in overrides/ minimal

If both tools became unavailable, our content is portable to any other Markdown-based static site generator (Docusaurus, Astro Starlight, etc.) with relatively limited rewrite effort.

References