chore: switch the Read the Docs build to Zensical - #104
Merged
Conversation
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
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
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.
Follows the trial in #102. Zensical reads the same
mkdocs.yml, runs themain.pymacros natively, and the output matched the MkDocs build page for page, so production moves over before Material for MkDocs reaches end of life on 2026-11-05.Changes
.readthedocs.yml– Python 3.12, installrequirements-zensical.txt, runzensical buildand copysite/to the output directory, per the official Read the Docs Zensical guide.mkdocs.yml– explicitsite_url: https://docs.bentobox.world/en/latest/, since Zensical cannot readREADTHEDOCS_CANONICAL_URL. Verified the canonical link in the built HTML.CLAUDE.md,requirements-zensical.txt, workflow comments – Zensical is now the primary build;requirements.txtis kept as the MkDocs fallback.Rollback is a one-file revert of
.readthedocs.yml.Known difference: no "last updated" line in the footer, as Zensical has no
git-revision-date-localizedsupport yet.Tip: set a
GITHUB_TOKENenvironment variable in the Read the Docs project settings so thetranslations()macro is not rate-limited during builds.🤖 Generated with Claude Code
https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS