Skip to content

Migrate the documentation build to Zensical - #3135

Open
kattni wants to merge 4 commits into
beeware:mainfrom
kattni:tooling/zensical-migration
Open

kattni wants to merge 4 commits into
beeware:mainfrom
kattni:tooling/zensical-migration

Conversation

@kattni

@kattni kattni commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Migrates the Briefcase documentation build from MkDocs to Zensical, using native Zensical configuration.

This depends on beeware/beeware-docs-tools#288, which moves docs-tools to Zensical. Until that PR merges, the docs dependency group is temporarily pinned to its branch (kattni/beeware-docs-tools@tooling/zensical-migration) so this PR can build. The pin will be reverted to docs-tools main once #288 is merged; this PR shouldn't merge before then.

Changes

  • Native Zensical config. docs/config.yml and docs/mkdocs.en.yml are replaced by docs/zensical.toml (shared) and docs/zensical.en.toml (English), generated with the docs-tools convert_mkdocs_config converter. The literate-nav docs/en/SUMMARY.md is replaced by a native nav in zensical.toml; its one glob (how-to/publishing/*) is expanded.
  • Host Platform Support table headers. The 12 platform reference pages linked the table header with a hand-written relative href in raw HTML. Zensical rewrites raw-HTML links relative to the source file, so those links came out one level too high (a 404 on Read the Docs). They're now Markdown links via md_in_html, which render the same and are validated by the build. md_in_html is also added to the pyspelling Markdown pipeline so the link targets aren't spell-checked.
  • Housekeeping. .gitignore ignores the generated docs/_build.*.toml; tox.ini drops the MkDocs 2 warning environment variables; .specify/memory/constitution.md now says Zensical instead of MkDocs.

Verification

  • tox -e docs-en (strict) and tox -e docs-lint pass against the pinned docs-tools branch.
  • Compared with a MkDocs build of main: page text, resolved link targets, page titles and the sidebar nav match on every page. The only text differences are 4 contribution-guide pages, where docs-tools' shared content now says to edit nav in zensical.toml instead of SUMMARY.md. Remaining differences are theme-level (for example, Zensical's compact search box).
  • An English plus synthetic French build also passes, with translated shared content and all static files copied.

Notes for reviewers

  • AGENTS.md still describes the docs as MkDocs ("Docs: MkDocs", "MkDocs documentation"). It's left unchanged here because AGENTS.md is only edited on explicit direction; it should be updated to Zensical, here or in a follow-up.
  • pymdownx.magiclink.repo is "toga", carried over unchanged from the old config. That may be unintended for Briefcase.
  • Zensical ignores some carried-over settings: autorefs resolve_closest, and the omitted_files and unrecognized_links validation keys. They're kept for parity with docs-tools' own config; autoref resolution matches the MkDocs build regardless.
  • [tool.rumdl] flavor = "mkdocs" in pyproject.toml is left alone; it selects a Markdown dialect, not the build tool.

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)

The raw-HTML hrefs in the platform support tables resolved one level too
high under Zensical, which rewrites links in raw HTML. Markdown links via
md_in_html resolve correctly and are validated by the build. Add
md_in_html to the pyspelling Markdown pipeline so link targets aren't
spell-checked as prose.
Convert the MkDocs config (config.yml, mkdocs.en.yml) to native Zensical
config (zensical.toml, zensical.en.toml) with the docs-tools converter,
replacing the literate-nav SUMMARY.md with a native nav. Ignore the
generated build config, drop the MkDocs 2 warning variables from tox, and
update the constitution's docs tooling reference.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant