Repository navigation
Conversation
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.
Revert to beeware/main once beeware/beeware-docs-tools#288 is merged.
3 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
docsdependency 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-toolsmainonce #288 is merged; this PR shouldn't merge before then.Changes
docs/config.ymlanddocs/mkdocs.en.ymlare replaced bydocs/zensical.toml(shared) anddocs/zensical.en.toml(English), generated with the docs-toolsconvert_mkdocs_configconverter. The literate-navdocs/en/SUMMARY.mdis replaced by a nativenavinzensical.toml; its one glob (how-to/publishing/*) is expanded.hrefin 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 viamd_in_html, which render the same and are validated by the build.md_in_htmlis also added to the pyspelling Markdown pipeline so the link targets aren't spell-checked..gitignoreignores the generateddocs/_build.*.toml;tox.inidrops the MkDocs 2 warning environment variables;.specify/memory/constitution.mdnow says Zensical instead of MkDocs.Verification
tox -e docs-en(strict) andtox -e docs-lintpass against the pinned docs-tools branch.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 editnavinzensical.tomlinstead ofSUMMARY.md. Remaining differences are theme-level (for example, Zensical's compact search box).Notes for reviewers
AGENTS.mdstill 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.repois"toga", carried over unchanged from the old config. That may be unintended for Briefcase.resolve_closest, and theomitted_filesandunrecognized_linksvalidation keys. They're kept for parity with docs-tools' own config; autoref resolution matches the MkDocs build regardless.[tool.rumdl] flavor = "mkdocs"inpyproject.tomlis left alone; it selects a Markdown dialect, not the build tool.PR Checklist:
Assisted-by: Claude Code (Claude Opus 5.5)