The decision

In one line

Build on MkDocs + Material now; move to Zensical when it is the clear winner.

Why

MkDocs + Material is mature and ships today: a large plugin ecosystem, mike versioning, and a configuration surface that LLM agents generate reliably. Zensical - by the same author (Martin Donath) - is the intended successor, but it is still pre-1.0, with most of its advantages on the roadmap.

The migration is cheap by design: Zensical reads the same mkdocs.yml, the same Material settings and the same Python-Markdown extensions. So this site is written once and can be served by either tool.

graph LR
  A["Markdown + mkdocs.yml"] --> B{Build}
  B -->|now| C["MkDocs + Material"]
  B -->|later| D["Zensical"]
  C --> E["Cloudflare"]
  D --> E

Do not adopt MkDocs 2.0

MkDocs 1.x is unmaintained, and MkDocs 2.0 removes the plugin system, rewrites theming and offers no migration path. Material for MkDocs pins mkdocs<2 so builds keep working. Stay on MkDocs 1.x + Material, or move to Zensical - not MkDocs 2.0.

How it was verified

The same mkdocs.yml was built with both toolchains - MkDocs 1.6.1 + Material 9.7.7 and Zensical 0.0.67 - with no changes required.

Re-evaluate at Zensical 0.1.0

Zensical 0.1.0 is slated for 2026-11-05. That is the trigger to test it again and decide whether to switch.