Upgrade trestle to use MkDocs 2.0

[degenaro]

Issue description / feature objectives

cmd [2] | mkdocs build -c -s
│ ⚠ WARNING – MkDocs 2.0 is incompatible with Material for MkDocs
│
│ MkDocs 1.x is unmaintained. We recommend switching to Zensical, our
│ new static site generator, as soon as possible. We're providing an
│ analysis of the situation in this article:
│
│ https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

Caveats / Assumptions

MkDocs 1.x is no longer supported

Completion Criteria

Upgraded to MkDocs 2.0

[nXtCyberNet]

hi @degenaro , can i work on this ?

[nXtCyberNet]

Hi @degenaro — I wanted to flag a clarification on the issue title and completion criteria before this gets picked up.

The build warning actually recommends against upgrading to MkDocs 2.0 for Material-based projects. MkDocs 2.0 removes the plugin system entirely and uses TOML-based config, making our existing mkdocs.yml and full plugin stack incompatible with no migration path. The recommended path from the Material team is Zensical, their new SSG.

However, I'd caution against an immediate Zensical migration as well. Here's a full breakdown of our current docs dependency stack against Zensical's compatibility status:

Plugin	Zensical Status	Notes
mkdocs-material	✅ Native	Core theme supported natively
mkdocs-minify-plugin	✅ Planned Native	Zensical will include minification natively
mkdocs-git-revision-date-localized-plugin	✅ Planned Native	Git metadata will be natively integrated
mkdocs-awesome-pages-plugin	✅ Planned Native	Covered by Zensical's modular navigation system
mike	✅ Planned Native	Versioning will be natively supported with improved workflows
pymdown-extensions	✅ Compatible	Python Markdown extensions work as-is
markdown-include	⚠️ Unconfirmed	Not listed in Zensical's native roadmap; may need module system
mkdocstrings[python]>=0.25.2	⚠️ Partial / Blocker	Preliminary support added, but cross-references and backlinks not yet supported
mkdocs-htmlproofer-plugin	❌ Gap	Not listed in Zensical's native roadmap; no module system yet
pillow / cairosvg	⚠️ Unconfirmed	Used for social cards in Material; Zensical compatibility unverified
livereload	⚠️ Unconfirmed	Internal dev server dependency; needs testing

The critical blocker is mkdocstrings[python]. Zensical has added preliminary support, but cross-references and backlinks between documented objects are not yet functional. For compliance-trestle, which documents interconnected OSCAL object models and Python APIs, this is a real functional regression — not a cosmetic gap.

Additionally, mkdocs-htmlproofer-plugin and markdown-include have no confirmed path in Zensical's current roadmap. These will depend on the module system, which is still upcoming.

Suggested approach:

1. Short-term (immediate): Pin mkdocs<2.0.0 in pyproject.toml to prevent CI breakage when MkDocs 2.0 officially releases.
2. Log hygiene: Set NO_MKDOCS_2_WARNING=1 in the docs workflow environment to suppress the warning while we plan the migration.
3. Watch: Monitor Zensical's GitHub for cross-reference/backlink support in mkdocstrings and the module system launch before committing to migration.
4. Migrate: Once the above gaps are resolved, Zensical is designed for near-seamless migration from existing mkdocs.yml configs.

Happy to submit a PR for the version pin as an immediate safeguard if that's useful.

[rishi-jat]

@degenaro , can you please assign this issue to me ? Thanks!

[Aditya-Aryan-6914]

Hi, the problem has been solved on my end. Have a look. If any change is required, please tell me

[Acuspeedster]

Imporatant: @degenaro check out #2132 after checking #2131