Skip to content

Migrate the documentation from MkDocs to Zensical - #357

Merged
joelwurtz merged 3 commits into
mainfrom
zensical
Oct 24, 2026
Merged

joelwurtz merged 3 commits into
mainfrom
zensical

Conversation

@pyrech

@pyrech pyrech commented Oct 22, 2026 •

Copy link
Copy Markdown
Member

Same move as jolicode/castor#918. Zensical is the successor of Material for MkDocs, built by the same team.

  • mkdocs.yaml converted to zensical.toml.
  • The documentation is now built in Docker (docs/Dockerfile) instead of a local Python with poetry: castor doc:build, castor doc:server, and castor doc:build-github-pages run Zensical and mike in the container. pyproject.toml and poetry.lock are gone, as well as the Python setup in the workflow.
  • Versioning keeps using mike, through the Zensical-compatible fork maintained by the Zensical team until native versioning ships. The tagged versions keep their mkdocs.yaml, which Zensical reads as-is.
  • Stylesheet switched to Zensical/extra.css from jolicode/oss-theme, which keeps the current colors with the modern variant.
  • _nav.md, the overrides/ templates and the Dockerfile are excluded from the published site (_nav/ and overrides/*.html were published so far).

Checked locally: the latest build has the same structure and the same 113 code blocks as production, and a full doc:build-github-pages run in a scratch clone produced the same 12 versions and the same versions.json as production.

Two extra commits:

  • The GitHub Actions are pinned to the commit of their latest release, and a Dependabot config keeps them updated (monthly, grouped).
  • A doc job in the CI builds the documentation on each PR, in strict mode so that a broken link fails the build.

@joelwurtz

Copy link
Copy Markdown
Member

Thanks

@joelwurtz
joelwurtz merged commit 252f435 into main Oct 24, 2026
6 checks passed
@joelwurtz
joelwurtz deleted the zensical branch October 24, 2026 22:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants