docs: pin mkdocs<2 and silence the mkdocs-material advisory banner in CI#3072
Conversation
MkDocs 2.0 is a ground-up rewrite that drops the plugin system, so it is incompatible with mkdocs-material and the rest of our docs plugin stack. mkdocs-material itself pins mkdocs<2 as of 9.7.5; mirror that bound on our direct dependency so a future re-lock cannot resolve 2.0, and bump the locked mkdocs-material from 9.7.2 to 9.7.6 (banner moved to stderr, sandboxed social plugin, upstream mkdocs<2 pin). mkdocs-material >=9.7.2 also prints a red advisory banner on every build; set NO_MKDOCS_2_WARNING=1 in the docs CI jobs to keep it out of build logs. Local builds still show it.
📚 Documentation preview
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — docs/CI dependency hygiene only: an upper bound on a docs-group dependency, a lockfile bump, and a cosmetic env var in three docs CI steps.
Extended reasoning...
Overview
The PR touches only the docs toolchain: adds an upper bound (mkdocs>=1.6.1,<2) to the docs dependency group in pyproject.toml (mirrored in uv.lock's requirements block), bumps mkdocs-material 9.7.2 → 9.7.6 in the lockfile, and sets NO_MKDOCS_2_WARNING=1 on the three docs-build steps in deploy-docs.yml, docs-preview.yml, and shared.yml. No runtime SDK code, tests, or published-package dependencies are affected.
Security risks
None of substance. The workflow edits only add a step-level environment variable to existing steps — no new triggers, permissions, secrets, or third-party actions. The docs-preview workflow's security-sensitive authorization logic is untouched. The lockfile bump is a patch-level upgrade of a docs-only dependency with pinned hashes, and 9.7.6 actually tightens the social-cards template sandboxing per the release notes.
Level of scrutiny
Low. This is dev-tooling/CI hygiene with no effect on the shipped mcp package or its runtime dependencies. The new upper bound is on a dev-group dependency and matches the posture mkdocs-material itself adopted upstream (its own mkdocs<2 pin in 9.7.5), so it is not a controversial design decision. The AGENTS.md guidance about not raising floors for CVEs is not implicated — no floor changes, only a cap on a docs tool.
Other factors
The docs-preview build for this PR completed and deployed successfully, which exercises the new lock and env var end to end. The strict-mode docs job in shared.yml also builds against the updated lock on every PR, so any incompatibility introduced by the material bump would surface immediately in CI. The bug hunting system reported no issues, and there are no outstanding reviewer comments.
1 participant
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<2pin in 9.7.5; the Material team's analysis is here.Three changes:
mkdocs>=1.6.1,<2in the docs group. Our locked mkdocs-material (9.7.2) predates the upstream pin, and if 2.0 is ever published to PyPI under themkdocsname, 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<2pin.NO_MKDOCS_2_WARNING=1in 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.ymlalso builds thev1.xbranch, whose pyproject has an unboundedmkdocs>=1.6.1. It's protected today by its frozen lockfile and by mkdocs-material 9.6.19's ownmkdocs~=1.6requirement, 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 --strictpasses on 9.7.6; the banner goes to stderr only, and disappears withNO_MKDOCS_2_WARNING=1set. Verified the generated site is intact (api/reference pages,llms.txt), thatuv lock --checkpasses with the new specifier, and that the step-levelenv:propagates throughscripts/build-docs.shto both branch builds. Also confirmed social cards still render on 9.7.6's sandboxed environment whenENABLE_SOCIAL_CARDSis set.Breaking Changes
None — CI/dependency hygiene only; no API or rendered-docs changes.
Types of changes
Checklist
Additional context
The
NO_MKDOCS_2_WARNINGenv 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-mkdocsentry points, so wrapper tools likemikeare unaffected.AI Disclaimer