Skip to content

Migrate the documentation from MkDocs to Zensical - #29

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

joelwurtz merged 3 commits into
mainfrom
zensical

Conversation

@pyrech

@pyrech pyrech commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

Same migration as jolicode/castor#918: Zensical is the successor of Material for MkDocs by the same team. The build stays in Docker (no cairo needed any more for the social cards), tools/mkdocs/ becomes tools/doc/ and the include-markdown directives become markdown() macros (tools/doc/main.py).

Most pages show Twig syntax (the Dockerfile templates), so the macros are opt-in: only index.md and changelog.md declare render_macros: true.

Output checked against a MkDocs build of the same sources: same 30 pages and social cards, same content, headings, admonitions and code blocks. The relative links of the included CHANGELOG.md are now resolved to pages (they were left as .md links before). The modern theme variant brings the JoliCode colors from oss-theme/Zensical/extra.css. Only visible changes: the Zensical search widget, the "On this page" wording and the section index no longer repeated at the top of the sidebar.

Also in separate commits: two links to the ghcr.io section used a wrong anchor (the strict build catches it now), and a docs CI job building the documentation.

@joelwurtz
joelwurtz merged commit 2049628 into main Oct 27, 2026
5 of 6 checks passed
@joelwurtz
joelwurtz deleted the zensical branch October 27, 2026 10:24
@joelwurtz

Copy link
Copy Markdown
Contributor

Thanks

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