chore: switch the Read the Docs build to Zensical - #40
Merged
Merged
Conversation
Mirrors BentoBoxWorld/docs#102 and #104. Material for MkDocs reaches end of life on 2026-11-05; Zensical reads the same mkdocs.yml and runs the main.py macros natively, and the local build output matches. - .readthedocs.yml: Python 3.12, install requirements-zensical.txt, run zensical build and copy site/ to the output directory. - mkdocs.yml: explicit site_url (Zensical cannot read READTHEDOCS_CANONICAL_URL) and theme.variant: classic. - .github/workflows/zensical.yml: builds with Zensical on every push/PR. - CLAUDE.md updated; requirements.txt kept as the MkDocs fallback. 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.
Mirrors BentoBoxWorld/docs#102 and BentoBoxWorld/docs#104. Material for MkDocs reaches end of life on 2026-11-05; Zensical is its successor from the same team, reads the same
mkdocs.yml, and runs themain.pymacros natively.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/zh-cn/latest/(Zensical cannot readREADTHEDOCS_CANONICAL_URL) andtheme.variant: classicto keep the Material look. MkDocs passes the extra key through..github/workflows/zensical.yml– runs the same build on every push and PR and checks macros and the footer override rendered.requirements-zensical.txt–zensical==0.0.59(pre-1.0, so pinned) plus PyYAML/requests.requirements.txtis kept as the MkDocs fallback.CLAUDE.md– build instructions updated.Verified locally (Zensical 0.0.59, Python 3.12): the site builds, the canonical link is
https://docs.bentobox.world/zh-cn/latest/…, the classic theme and the footer override render.Note: Zensical reports a number of pre-existing
anchor does not existwarnings in this repo (mostlyBentoBox/Translate-BentoBox-and-addons.md,FAQ.md,Glossary.md): in-page#anchorlinks whose targets are English heading slugs that no longer match the translated headings. They do not fail the build and are unrelated to this change, but are worth a follow-up.Rollback is a one-file revert of
.readthedocs.yml. Known difference: no "last updated" footer line, as Zensical has nogit-revision-date-localizedsupport yet.🤖 Generated with Claude Code
https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS