Skip to content

0001 — Build this site with Zensical

Status: Accepted, 2026-10-26 · Decided by: Joakim Persson

Context

The site needs a static site generator that turns a directory of Markdown files into a searchable website with diagrams.

The usual choice, MkDocs with the Material theme, is ending:

  • MkDocs 1.x has had no stable release since 1.6.1 (2024-08-30). MkDocs 2.0 is in pre-release.
  • According to the Material team, MkDocs 2.0 is a rewrite that is incompatible with Material and with the existing plugins.
  • The Material team has announced critical maintenance for Material for MkDocs only until 2027-05-05.

The Material team has built a successor, Zensical. It reads the same kind of Markdown, and its 0.1.0 release, planned for 2026-11-05, starts what the team calls a dependable release line.

The same choice was already made for the EGL documentation sites (egl-infra ADR 0007, 2026-09-18). Those sites have existing MkDocs configuration and move in two stages. This site has no MkDocs history and can start on Zensical directly.

Options

  1. MkDocs 1.x with Material. Works today, but both are reaching end of life.
  2. MkDocs 2.0. Incompatible with Material and its plugins.
  3. Zensical. Successor from the Material team. Pre-1.0.

Decision

Use Zensical, configured natively with zensical.toml (no mkdocs.yml), with the modern theme variant.

Measured on 2026-10-26 with Zensical 0.0.72:

  • zensical new creates a working project.
  • Mermaid diagrams render with the default configuration.
  • zensical build --strict fails on a link to a missing page (exit code 1) and succeeds on a clean tree (exit code 0), so CI can gate on it.
  • Wheels exist for Linux on amd64 and arm64 and for macOS, so the build runs on every runner and device we have.

Consequences

  • Zensical is pre-1.0 and releases roughly weekly. uv.lock pins the exact version, and upgrades are deliberate: uv lock --upgrade-package zensical, then a strict build.
  • Move to 0.1.x once it is out and has had a few point releases.
  • Pages stay plain Markdown with the common extensions (admonitions, tables, Mermaid), so the content would move to another generator with little work.