ADR-0050: Build the documentation with Zensical and publish it on GitHub Pages¶
Status¶
Accepted
Date¶
2026-11-17
Context¶
TyPy's documentation is 81 Markdown pages under docs/ in release 0.5.0:
the user documentation and the engineering documents. They are read on
GitHub, where a reader finds no navigation, no search and no page for the
release they run. DOC-05 asks for a site at https://typy-lang.org, built
in strict mode from the sources of each release. The pages stay what the
checks already read: markdownlint lints them, and the documentation test
judges every Python sample in them (DOC-04) and reads the troubleshooting
page that typy explain embeds (DOC-03).
The state of the Markdown site generators, read from their projects on 2026-11-17:
| Tool | State |
|---|---|
| MkDocs 1.6.1 | Unmaintained, and closed to outside contributions since 2026-10-02 |
| MkDocs 2.0 | A pre-release rewrite with no plugins, and no migration path that Material for MkDocs supports |
| Material for MkDocs 9.8.1 | In maintenance mode, with its end of life on 2027-05-05 |
| Zensical 0.1 | A stable line since 2026-11-05, from the team behind Material for MkDocs; it builds an existing mkdocs.yml project, with a subset of its plugins |
The sources are the announcement of Zensical (https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/), the releases of Material for MkDocs (https://github.com/squidfunk/mkdocs-material/releases), its notes on MkDocs 2.0 (https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/), and the discussion of MkDocs' maintenance (https://github.com/orgs/ProperDocs/discussions/33).
Zensical 0.1.1, tried on these pages on 2026-11-17, builds all of them in
about two seconds. Its strict mode fails on a link to a page or an anchor
that does not exist, and on a link that leaves docs/. It does not report
a page that the navigation leaves out, or a navigation entry whose page
does not exist, and it ignores the validation.nav settings that MkDocs
reads for both.
Options considered¶
- MkDocs 1.6.1 with Material for MkDocs 9.8. The site is built today, with tools that receive no fixes and that reach their end of life within six months.
- Zensical, from
mkdocs.yml. The pages stay Markdown and the configuration stays the one Material for MkDocs reads, so a return to Material is a change of the command that builds the site. - Sphinx. It is mature and links to the Python documentation through intersphinx. All 81 pages, markdownlint and the sample test of DOC-04 are Markdown, so the pages would be converted or read through a Markdown parser of Sphinx's, and its strength, documentation generated from Python source, gives nothing to a compiler written in Rust.
Decision¶
TyPy takes option 2.
- Tool. Zensical 0.1.1 with every dependency is pinned by version and
sha256 in
scripts/docs-requirements.txt.scripts/build-docs.shinstalls it into a CPython 3.14 environment once and runszensical build --strict --cleanintosite/.make docsruns the script in the dev container andmake checkrunsmake docs, so a broken link fails the quality gate. - Configuration.
mkdocs.ymlat the repository root holds only settings that Material for MkDocs 9.8 also reads. Icons come from the sets both ship, and the system fonts replace web fonts, so a page loads nothing from another host to show its text. The palette is the theme's deep purple, with an accent of TyPy's own indocs/stylesheets/extra.css, since the theme's accent gives the current page in the navigation less than the 4.5:1 contrast WCAG 2.2 level AA asks of text. - Navigation. The
navofmkdocs.ymlnames every page underdocs/, the decision records included, and the documentation test fails on a page it leaves out or a page it names that does not exist, which Zensical does not check. - Layout. The user documentation takes the sections of Python's
documentation, in its order: What's new, Tutorial, Library reference,
Language reference, Setup and usage, Extending and embedding, then
Diagnostics, which is TyPy's own. Section names and order are all that
is taken from the Python documentation; where TyPy behaves as CPython
does, a page links to https://docs.python.org rather than quoting it.
The engineering documents keep their directories, and the changelog page
includes
CHANGELOG.mdthroughpymdownx.snippets. - Publishing. The workflow
.github/workflows/pages.ymlbuilds the site withscripts/build-docs.shon the runner, with read-only permissions and without the dev image, and deploys it from a job that alone may write to Pages, in thegithub-pagesenvironment.release.ymlcalls it once it has created a release, since a release created with the workflow token starts noreleaseevent; a release published by hand starts it too, and it runs by hand on a release tag. The custom domain is a setting of the repository.
Consequences¶
- A reader gets navigation, search, light and dark modes and one URL per page, for the release they run.
- A broken link or anchor, or a page missing from the navigation, fails the quality gate, so the site stays whole between releases.
- Each decision record adds a line to the navigation in
mkdocs.yml. - Zensical is young: a 0.1 line that may change its configuration. The pin
keeps a build reproducible, and an upgrade is a change of the
requirements file that
make docschecks. - The site shows the documents of the last published release; changes on
mainwait for the next release.
Related requirements¶
DOC-01 to DOC-05.