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

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.

Author: maxisbey

.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",