Docs Site Tooling — MkDocs 1.x now, Zensical later

Trevor Bedford — 2026-04-09

Context

We need a static site generator for our internal docs site. MkDocs + mkdocs-material is the mature choice, but the ecosystem is in transition: MkDocs 2.0 is an unreleased rewrite that breaks all plugins and themes, and mkdocs-material has entered maintenance mode (through November 2026). The mkdocs-material team is building Zensical as the successor, which reads mkdocs.yml natively and is designed as a migration path.

Decision

Use MkDocs 1.x + mkdocs-material for the initial docs site. Plan to migrate to Zensical in a few months once it stabilizes.

To keep the migration painless:

• Minimal dependencies. Only mkdocs-material in requirements.txt — no extra MkDocs plugins beyond what material bundles.
• Standard markdown. Stick to features that Zensical will support: standard markdown, admonitions, KaTeX math, code blocks. Avoid deep reliance on MkDocs-specific plugin behavior.
• Simple config. Keep mkdocs.yml straightforward — no custom hooks, overrides, or theme customizations that would be hard to port.

Consequences

• We get a working docs site today with excellent search, navigation, and math support.
• We accept that mkdocs-material is in maintenance mode — no new features, but stable through late 2026.
• When Zensical is ready, migration should be straightforward because we kept the install clean and avoided MkDocs-specific complexity.
• We skip MkDocs 2.0 entirely — it has no plugin support, no migration path, and an uncertain future.