#3072 docs: pin mkdocs<2 and silence the mkdocs-material advisory banner in CI

Hardens the docs toolchain against the upcoming MkDocs 2.0 split and quiets the advisory banner mkdocs-material now prints on every build.

Motivation and Context

MkDocs 1.x is no longer receiving releases (latest is 1.6.1 from Aug 2024), and "MkDocs 2.0" is being developed as a ground-up rewrite (announcement) that removes the plugin system — so it's incompatible with mkdocs-material and every plugin we use (mkdocstrings, gen-files, literate-nav, glightbox). mkdocs-material entered maintenance mode in 9.7.0 and added its own mkdocs<2 pin in 9.7.5; the Material team's analysis is here.

Three changes:

• mkdocs>=1.6.1,<2 in the docs group. Our locked mkdocs-material (9.7.2) predates the upstream pin, and if 2.0 is ever published to PyPI under the mkdocs name, an unbounded re-lock could pick it up and break the docs build. Mirroring the bound on our direct dependency makes the guard independent of the theme's metadata.
• mkdocs-material 9.7.2 → 9.7.6 in the lockfile: moves the advisory banner from stdout to stderr, sandboxes the social-cards plugin's template environment, and carries the upstream mkdocs<2 pin.
• NO_MKDOCS_2_WARNING=1 in the three docs CI jobs, so the red banner stays out of build logs. Local builds still show it, which seems right — it's genuinely useful information for contributors.

This is the "pin and wait" posture most of the ecosystem has taken (e.g. pydantic and the astral repos pin mkdocs 1.6.1 + mkdocs-material 9.7.6). Zensical is the likely eventual destination, but it has no equivalent of gen-files (zensical/zensical#8), literate-nav (zensical/zensical#13), or MkDocs hooks: yet — our entire generated-API-reference and llms.txt pipeline — so migrating now isn't viable. Worth re-evaluating around November 2026 when mkdocs-material's committed maintenance window ends.

Note: deploy-docs.yml also builds the v1.x branch, whose pyproject has an unbounded mkdocs>=1.6.1. It's protected today by its frozen lockfile and by mkdocs-material 9.6.19's own mkdocs~=1.6 requirement, so no urgency, but a [v1.x] backport of the same bound would be reasonable hygiene.

How Has This Been Tested?

Built the docs locally against the updated lock: uv run --frozen mkdocs build --strict passes on 9.7.6; the banner goes to stderr only, and disappears with NO_MKDOCS_2_WARNING=1 set. Verified the generated site is intact (api/ reference pages, llms.txt), that uv lock --check passes with the new specifier, and that the step-level env: propagates through scripts/build-docs.sh to both branch builds. Also confirmed social cards still render on 9.7.6's sandboxed environment when ENABLE_SOCIAL_CARDS is set.

Breaking Changes

None — CI/dependency hygiene only; no API or rendered-docs changes.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

The NO_MKDOCS_2_WARNING env var is mkdocs-material's only supported off-switch — a config-level option was declined upstream, and 9.7.6 already auto-suppresses the banner for non-mkdocs entry points, so wrapper tools like mike are unaffected.

_{AI Disclaimer}