From 3508198c20aa531ae4931bac0a592e0fa3a47464 Mon Sep 17 00:00:00 2001 From: tastybento Date: Sun, 6 Sep 2026 17:30:19 -0700 Subject: [PATCH 1/2] chore: switch the Read the Docs build to Zensical 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 Claude-Session: https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS --- .github/workflows/zensical.yml | 38 ++++++++++++++++++++++++++++++++++ .readthedocs.yml | 29 ++++++++++++++++---------- CLAUDE.md | 10 ++++----- mkdocs.yml | 4 ++++ requirements-zensical.txt | 13 ++++++++++++ 5 files changed, 78 insertions(+), 16 deletions(-) create mode 100644 .github/workflows/zensical.yml create mode 100644 requirements-zensical.txt diff --git a/.github/workflows/zensical.yml b/.github/workflows/zensical.yml new file mode 100644 index 0000000..68b2919 --- /dev/null +++ b/.github/workflows/zensical.yml @@ -0,0 +1,38 @@ +# Builds the site with Zensical, the same tool Read the Docs uses for +# production (see .readthedocs.yml), and checks the output is sane. +name: Zensical build + +on: + push: + branches: [master] + pull_request: + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + cache-dependency-path: requirements-zensical.txt + - run: pip install -r requirements-zensical.txt + - run: zensical build + env: + # Lifts the unauthenticated GitHub rate limit used by the + # translations() macro in main.py. + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + - name: Sanity-check output + run: | + test -f site/index.html + test -f site/addons/Level/index.html + # Macros must have rendered, not been passed through as text. + ! grep -rl '{{ *addon_description' site + grep -q 'md-footer-policies__link' site/FAQ/index.html + - uses: actions/upload-artifact@v4 + with: + name: zensical-site + path: site + retention-days: 7 diff --git a/.readthedocs.yml b/.readthedocs.yml index af6e88c..db0833d 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,22 +1,29 @@ # .readthedocs.yml # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# +# The site is built with Zensical (https://zensical.org), the successor to +# Material for MkDocs. It reads mkdocs.yml directly. Setup follows the official +# guide: https://docs.readthedocs.com/platform/stable/intro/zensical.html +# +# To fall back to MkDocs, restore the `mkdocs:` section and point +# python.install at requirements.txt. -# Required version: 2 -# Set the version of Python and other tools you might need build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: - python: "3.11" + python: "3.12" + jobs: + build: + html: + - zensical build + post_build: + # Copy the built site into the directory Read the Docs publishes. + - mkdir -p $READTHEDOCS_OUTPUT/html/ + - cp --recursive site/* $READTHEDOCS_OUTPUT/html/ -# Build documentation with MkDocs -mkdocs: - configuration: mkdocs.yml - -# We recommend specifying your dependencies to enable reproducible builds: -# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html python: install: - - requirements: requirements.txt + - requirements: requirements-zensical.txt diff --git a/CLAUDE.md b/CLAUDE.md index 2b07638..20d8aa0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,17 +4,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## What this repo is -Chinese translation of the BentoBoxWorld documentation site. It is an MkDocs (Material theme) project that publishes the user-facing docs for BentoBox, its game modes, and its addons. The English source lives at https://github.com/BentoBoxWorld/docs — this repo mirrors that structure with content translated into Chinese. The current working branch is typically `update/sync-with-english`, which is used to pull new English content over and translate it. +Chinese translation of the BentoBoxWorld documentation site. It is a [Zensical](https://zensical.org) project (the successor to Material for MkDocs; it reads the MkDocs-style `mkdocs.yml`) that publishes the user-facing docs for BentoBox, its game modes, and its addons. The English source lives at https://github.com/BentoBoxWorld/docs — this repo mirrors that structure with content translated into Chinese. The current working branch is typically `update/sync-with-english`, which is used to pull new English content over and translate it. ## Common commands ```bash -pip install -r requirements.txt # install MkDocs + plugins (pinned old versions, see note below) -mkdocs serve # local preview at http://127.0.0.1:8000 -mkdocs build # build static site into ./site +pip install -r requirements-zensical.txt # Python 3.10+; installs Zensical (no MkDocs packages needed) +zensical serve # local preview at http://localhost:8000 +zensical build # build static site into ./site ``` -Note: `requirements.txt` pins fairly old versions (mkdocs 1.3.0, mkdocs-material 8.2.15, macros 0.6.0). If installing fresh, use a venv to avoid conflicts with system packages. +Note: `requirements.txt` is the MkDocs fallback (`pip install -r requirements.txt && mkdocs build`); Zensical reads the same `mkdocs.yml`. Read the Docs runs `zensical build` on Python 3.12 (see `.readthedocs.yml`), and `.github/workflows/zensical.yml` runs the same build on every push and PR. Zensical does not support the `git-revision-date-localized` plugin, so the "last updated" line is not shown. ## Architecture diff --git a/mkdocs.yml b/mkdocs.yml index a9e9022..3bc9565 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,6 @@ site_name: BentoBox World +# Zensical cannot read READTHEDOCS_CANONICAL_URL, so the canonical URL is set explicitly. +site_url: https://docs.bentobox.world/zh-cn/latest/ copyright: "© Copyright 2017-2026 tastybento and the BentoBoxWorld community (CC-BY 4.0)." repo_url: https://github.com/BentoBoxWorld/BentoBox repo_name: BentoBoxWorld/BentoBox @@ -89,6 +91,8 @@ nav: theme: name: material custom_dir: overrides + # Zensical-only: keep the Material for MkDocs look. MkDocs passes unknown theme keys through. + variant: classic palette: scheme: slate primary: deep orange diff --git a/requirements-zensical.txt b/requirements-zensical.txt new file mode 100644 index 0000000..54578c0 --- /dev/null +++ b/requirements-zensical.txt @@ -0,0 +1,13 @@ +# Production build with Zensical (https://zensical.org), the successor to +# Material for MkDocs from the same team. Reads the same mkdocs.yml and runs +# the macros in main.py natively, so no MkDocs packages are needed. +# +# python3 -m venv .venv && .venv/bin/pip install -r requirements-zensical.txt +# .venv/bin/zensical build # or: zensical serve +# +# Requires Python 3.10+. Zensical is pre-1.0, so the version is pinned exactly. +# Read the Docs installs this file (see .readthedocs.yml). requirements.txt is +# kept as the MkDocs fallback. +zensical==0.0.59 +PyYAML>=6.0 +requests>=2.31 From fe3f981048e05b9639c2969b8fb30acc54f5489f Mon Sep 17 00:00:00 2001 From: tastybento Date: Sun, 6 Sep 2026 17:31:32 -0700 Subject: [PATCH 2/2] 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 Claude-Session: https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS --- .readthedocs.yml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index db0833d..383ccad 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -6,8 +6,8 @@ # Material for MkDocs. It reads mkdocs.yml directly. Setup follows the official # guide: https://docs.readthedocs.com/platform/stable/intro/zensical.html # -# To fall back to MkDocs, restore the `mkdocs:` section and point -# python.install at requirements.txt. +# To fall back to MkDocs, restore the `mkdocs:` section, drop build.jobs and +# use python.install with requirements.txt. version: 2 @@ -16,6 +16,9 @@ build: tools: python: "3.12" jobs: + # python.install only runs for sphinx/mkdocs builds, so install here. + install: + - pip install -r requirements-zensical.txt build: html: - zensical build @@ -23,7 +26,3 @@ build: # Copy the built site into the directory Read the Docs publishes. - mkdir -p $READTHEDOCS_OUTPUT/html/ - cp --recursive site/* $READTHEDOCS_OUTPUT/html/ - -python: - install: - - requirements: requirements-zensical.txt