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..383ccad 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,22 +1,28 @@ # .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, drop build.jobs and +# use python.install with 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" - -# 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 + 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 + post_build: + # Copy the built site into the directory Read the Docs publishes. + - mkdir -p $READTHEDOCS_OUTPUT/html/ + - cp --recursive site/* $READTHEDOCS_OUTPUT/html/ 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