[kattni]

Migrates the BeeWare documentation tooling from MkDocs (with Material for MkDocs) to Zensical, and moves the configuration to Zensical's native file formats.

What changes

• Build and live serve run zensical build / zensical serve (Zensical 0.1.0, pinned exactly, as it's pre-1.0). The MkDocs build path is removed.
• Configuration moves from docs/config.yml + docs/mkdocs.<lang>.yml (YAML with INHERIT and !ENV) to docs/zensical.toml + per-language docs/zensical.<lang>.toml:
  • docs-tools merges the two with the same rule INHERIT used: tables merge, lists and values replace.
  • A language file that sets anything other than the per-language settings produces a warning.
  • site_url is filled in from Read the Docs when it isn't set.
• Navigation moves from literate-nav (docs/en/SUMMARY.md) to the native nav setting.
• Theme overrides are preserved, with fixes for Zensical:
  • The language selector links, header search, the homepage <title>, and the TOC text size.
  • The classic theme variant and macros on_error_fail are set by default at build time.
• Translated builds:
  • Each translation gets its own site_url, including the language directory. This fixes canonical links, sitemaps and 404 pages that pointed at the English site. That problem predates this PR.
  • Images and other resources are copied file by file, because Zensical doesn't follow symlinked directories.
  • mkdocstrings ::: blocks with an options: block are kept out of the translation catalogs and restored after po2md, which joins them onto one line and breaks the build. The docs-tools test page now exercises this.
• Dependencies: mkdocs-material, the macros plugin fork, mkdocs-literate-nav and mkdocs-rss-plugin are dropped. mkdocs stays, with a comment explaining why: mkdocstrings imports it when it runs; it's not used to build anything. Dropping mkdocs-rss-plugin was verified on the website: its feeds are byte-identical, apart from build timestamps, without the plugin installed.

Translations

The translation workflow (md2po/po2md, Weblate, DeepL) is unchanged.

• Navigation titles now have their own context (msgctxt "navigation"). This keeps them separate from page headings with the same text, which often had a different translation.
  • All 760 navigation title translations in docs-tools match what main displays.
  • In other repositories, untranslated navigation entries are filled in from their previous translations on the next translation run.
• Changed strings: existing translations were ported to the new wording where possible:
  • 197 translations carried over exactly, 24 of them human-reviewed.
  • 25 kept and marked for review, 9 of them human-reviewed.
  • Strings whose content was rewritten (for example, YAML examples that are now TOML) are left for machine translation, so they don't show outdated instructions.
• Check: running the translation pipeline twice leaves all 19,456 entries unchanged.

Before merging: this PR edits every translations.po file, so lock Weblate and pull its pending changes first, as the translate.yml workflow does.

Notes for reviewers

• The conversion tooling isn't part of this PR. Each repository is converted once, using a converter kept on a separate branch, so it doesn't ship with docs-tools. That converter imports private zensical.config names, which is a further reason to keep it out.

• Downstream repositories: every repository that uses docs-tools needs converting before this merges. Once this merges, docs-tools no longer reads config.yml or SUMMARY.md, so any repository still using them stops building. Every one of them has an open migration PR:

  • Website: Migrate the website to Zensical beeware.github.io#842
  • Toga: Migrate docs build to Zensical toga#4868
  • Briefcase: Migrate the documentation build to Zensical briefcase#3135
  • Rubicon: Migrate the documentation build to Zensical rubicon-objc#864
  • Tutorial: Migrate the documentation from MkDocs to Zensical beeware-tutorial#98
  • toga-chart: Convert docs from MkDocs to Zensical toga-chart#347
  • Podium: Migrate the documentation from MkDocs to Zensical podium#103
  • xbuild: Migrate the documentation from MkDocs to Zensical xbuild#115
  • Colosseum: Migrate the documentation from MkDocs to Zensical colosseum#225
  • Cricket: Migrate the documentation from MkDocs to Zensical cricket#111

  Each of these PRs pins docs-tools to this branch, so it builds before this merges. Each pin needs reverting to main once this is merged.

• Verified locally:

  • tox -e docs-all (20 languages, strict).
  • tox -e py.
  • tox -e docs-lint.
  • pre-commit.
  • A comparison of article text against the MkDocs build of the same content.

PR Checklist:

• I will abide by the BeeWare Code of Conduct
• I have read and have followed the CONTRIBUTING.md file
• This PR was generated or assisted using an AI tool

Assisted-by: Claude Code (Claude Opus 5.5)