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 4841a74..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.9" - -# 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 cfeb29a..eddf09c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Repository purpose -French translation of the BentoBox documentation site (a Minecraft Bukkit plugin framework). The site is built with MkDocs + Material theme and published via Read the Docs. Almost all content is Markdown under `docs/`; the rest of the repo is the build configuration and a small set of macros that generate tables at build time. +French translation of the BentoBox documentation site (a Minecraft Bukkit plugin framework). The site is built with [Zensical](https://zensical.org) (the successor to Material for MkDocs; it reads the MkDocs-style `mkdocs.yml`) and published via Read the Docs. Almost all content is Markdown under `docs/`; the rest of the repo is the build configuration and a small set of macros that generate tables at build time. ## Common commands @@ -12,11 +12,11 @@ Use the in-repo virtualenv (`.venv/`) or install requirements first: ```bash pip install -r requirements.txt -mkdocs serve # local preview at http://127.0.0.1:8000 -mkdocs build # output to ./site +zensical serve # local preview at http://localhost:8000 +zensical build # output to ./site ``` -Read the Docs uses Python 3.9 and `mkdocs.yml` as the entry point (see `.readthedocs.yml`). There are no tests or linters. +Read the Docs uses Python 3.12 and runs `zensical build` (see `.readthedocs.yml`); `.github/workflows/zensical.yml` runs the same build on every push and PR. `requirements.txt` is kept as the MkDocs fallback (`pip install -r requirements.txt && mkdocs build`); Zensical does not support the `git-revision-date-localized` plugin, so the "last updated" line is not shown. There are no tests or linters. ## Architecture diff --git a/mkdocs.yml b/mkdocs.yml index ca28fa6..bc843e7 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/fr/latest/ copyright: "© Copyright 2017-2026 tastybento et la communauté BentoBoxWorld (CC-BY 4.0)." repo_url: https://github.com/BentoBoxWorld/BentoBox repo_name: BentoBoxWorld/BentoBox @@ -90,6 +92,8 @@ nav: theme: name: material custom_dir: overrides + # Zensical-only: keep the Material for MkDocs look. MkDocs passes unknown theme keys through. + variant: classic language: fr palette: scheme: slate 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