chore: add Zensical trial build alongside MkDocs - #102
Merged
Merged
Conversation
Material for MkDocs reaches end of life on 2026-11-05. Zensical, from the same team, reads the existing mkdocs.yml and runs the main.py macros natively, so this repo can be built with either tool from one config. - requirements-zensical.txt: zensical pinned (pre-1.0) plus PyYAML/requests for main.py; no MkDocs packages needed. - .github/workflows/zensical.yml: builds with Zensical on every push/PR and checks macros and the footer override rendered. - mkdocs.yml: theme.variant: classic keeps the Material look under Zensical; MkDocs passes the key through unchanged (verified with a strict build). - CLAUDE.md: document the dual build and the one known gap (git-revision-date-localized is not supported by Zensical). Production on Read the Docs is unchanged and still builds with MkDocs. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS
This was referenced Sep 7, 2026
tastybento
added a commit
that referenced
this pull request
Sep 7, 2026
* chore: switch the Read the Docs build to Zensical Material for MkDocs reaches end of life on 2026-11-05. Zensical was trialled in #102 (same mkdocs.yml, native macros, classic theme variant) and the output matches the MkDocs build, so production moves over. - .readthedocs.yml: Python 3.12, install requirements-zensical.txt, run zensical build and copy site/ to the output directory, following the official Read the Docs Zensical guide. - mkdocs.yml: explicit site_url, since Zensical cannot read READTHEDOCS_CANONICAL_URL. - CLAUDE.md, requirements-zensical.txt, workflow comments updated; requirements.txt and the mkdocs: fallback are documented for rollback. Known difference: the "last updated" line from git-revision-date-localized is no longer shown, as Zensical does not support that plugin yet. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS * fix(rtd): install Zensical via build.jobs.install python.install is only run for sphinx/mkdocs builds, so with build.jobs alone the zensical command was not found on Read the Docs. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Material for MkDocs reaches end of life on 2026-11-05. Zensical is its successor from the same team, reads the existing
mkdocs.yml, and runs themain.pymacros natively. This PR keeps the repo buildable with both tools so a later switch of the production build is a config change rather than a migration. Read the Docs is untouched and still builds with MkDocs.What's added
requirements-zensical.txt–zensical==0.0.59(pre-1.0, so pinned exactly) plus PyYAML/requests formain.py. No MkDocs packages needed..github/workflows/zensical.yml– runszensical buildon every push and PR, and checks that macros and the footer override actually rendered.mkdocs.yml–theme.variant: classickeeps the Material look under Zensical. MkDocs passes the key through; verified withmkdocs build --strict.CLAUDE.md– documents the dual build.Verified locally (Zensical 0.0.59, Python 3.12)
Known gap
git-revision-date-localizedisn't supported by Zensical yet, so the "last updated" line is omitted in Zensical builds. It's still present in the MkDocs/production build.🤖 Generated with Claude Code
https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS