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

.github/workflows/deploy-docs.yml

@@ -49,6 +49,9 @@ jobs:
 
       - name: Build combined docs (v1.x at /, main at /v2/)
         run: bash scripts/build-docs.sh site
+        env:
+          # Silence mkdocs-material's MkDocs 2.0 warning banner in CI logs.
+          NO_MKDOCS_2_WARNING: "1"
 
       - name: Configure Pages
         uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

.github/workflows/docs-preview.yml

@@ -130,6 +130,9 @@ jobs:
 
       - run: uv sync --frozen --group docs
       - run: uv run --frozen --no-sync mkdocs build
+        env:
+          # Silence mkdocs-material's MkDocs 2.0 warning banner in CI logs.
+          NO_MKDOCS_2_WARNING: "1"
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

.github/workflows/shared.yml

@@ -125,3 +125,6 @@ jobs:
 
       - name: Build the docs in strict mode
         run: uv run --frozen --no-sync mkdocs build --strict
+        env:
+          # Silence mkdocs-material's MkDocs 2.0 warning banner in CI logs.
+          NO_MKDOCS_2_WARNING: "1"

pyproject.toml

@@ -76,7 +76,9 @@ dev = [
     "opentelemetry-sdk>=1.39.1",
 ]
 docs = [
-    "mkdocs>=1.6.1",
+    # MkDocs 2.0 is a ground-up rewrite (no plugin system) that is incompatible
+    # with mkdocs-material and every plugin below; stay on the 1.x line.
+    "mkdocs>=1.6.1,<2",
     "mkdocs-gen-files>=0.5.0",
     "mkdocs-glightbox>=0.4.0",
     "mkdocs-literate-nav>=0.6.1",

uv.lock

@@ -1016,7 +1016,7 @@ dev = [
     { name = "trio", specifier = ">=0.26.2" },
 ]
 docs = [
-    { name = "mkdocs", specifier = ">=1.6.1" },
+    { name = "mkdocs", specifier = ">=1.6.1,<2" },
     { name = "mkdocs-gen-files", specifier = ">=0.5.0" },
     { name = "mkdocs-glightbox", specifier = ">=0.4.0" },
     { name = "mkdocs-literate-nav", specifier = ">=0.6.1" },
@@ -1593,7 +1593,7 @@ wheels = [
 
 [[package]]
 name = "mkdocs-material"
-version = "9.7.2"
+version = "9.7.6"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "babel" },
@@ -1608,9 +1608,9 @@ dependencies = [
     { name = "pymdown-extensions" },
     { name = "requests" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/34/57/5d3c8c9e2ff9d66dc8f63aa052eb0bac5041fecff7761d8689fe65c39c13/mkdocs_material-9.7.2.tar.gz", hash = "sha256:6776256552290b9b7a7aa002780e25b1e04bc9c3a8516b6b153e82e16b8384bd", size = 4097818, upload-time = "2026-02-18T15:53:07.763Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/45/29/6d2bcf41ae40802c4beda2432396fff97b8456fb496371d1bc7aad6512ec/mkdocs_material-9.7.6.tar.gz", hash = "sha256:00bdde50574f776d328b1862fe65daeaf581ec309bd150f7bff345a098c64a69", size = 4097959, upload-time = "2026-03-19T15:41:58.161Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/cd/19/d194e75e82282b1d688f0720e21b5ac250ed64ddea333a228aaf83105f2e/mkdocs_material-9.7.2-py3-none-any.whl", hash = "sha256:9bf6f53452d4a4d527eac3cef3f92b7b6fc4931c55d57766a7d87890d47e1b92", size = 9305052, upload-time = "2026-02-18T15:53:05.221Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/01/bc663630c510822c95c47a66af9fa7a443c295b47d5f041e5e6ae62ef659/mkdocs_material-9.7.6-py3-none-any.whl", hash = "sha256:71b84353921b8ea1ba84fe11c50912cc512da8fe0881038fcc9a0761c0e635ba", size = 9305470, upload-time = "2026-03-19T15:41:55.217Z" },
 ]
 
 [package.optional-dependencies]