Zensical

Status: Under testing

In early May 2026 we started supporting Zensical as documentation generator as an alternative to MkDocs.

The main motivation is that MkDocs itself has been effectively unmaintained since its last release in August 2024, and the Material for MkDocs theme that most of our sites rely on is entering maintenance mode. Zensical is a ground-up rewrite by the Material for MkDocs author that consolidates the generator and the theme into a single project, remains compatible with existing mkdocs.yml configurations, and offers substantially faster incremental builds. See also The Collapse of MkDocs for broader context on the situation.

Initial testing has been satisfactory but the docs support for Zensical is still considered under testing.

This documentation will be updated as we make progress and consolidate relevant notes.

Using mkdocs.yml

You can still use your existing mkdocs.yml file as Zensical is compatible with MkDocs. A way to try this locally without having to touch any files, is to run:

uvx zensical serve --open

(uvx ships with uv; see Running tools if you don't have it yet.)

and review the generated documentation in your browser.

Note

Even though Zensical claims to support mkdocs.yml, check all important generated sections to verify nothing gets broken.

If all looks OK, and you want minimal changes to use Zensical for your site at docs, you can add "generator": "zensical" in .mbaridoc.json (create this file if needed):

{
  ...,
  "generator": "zensical"
}

Using zensical.toml

If your site is already configured for Zensical, no further changes are needed: the presence of zensical.toml at the root of your doc directory is enough for docs to pick Zensical as the generator.

Note

Regardless of the method, keep in mind that docs has a common set of dependencies for all hosted sites. Especially now that both MkDocs and Zensical are being supported, we still need to assess the risk of potential conflicts of some kind.