From 858dc5561988cd32235e034a5f48a584a4d1c86e Mon Sep 17 00:00:00 2001 From: Max Isbey <224885523+maxisbey@users.noreply.github.com> Date: Tue, 7 Jul 2026 09:59:59 +0000 Subject: [PATCH] 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. --- .github/workflows/deploy-docs.yml | 3 +++ .github/workflows/docs-preview.yml | 3 +++ .github/workflows/shared.yml | 3 +++ pyproject.toml | 4 +++- uv.lock | 8 ++++---- 5 files changed, 16 insertions(+), 5 deletions(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index b958fd23ab..fb16310757 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.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 diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index 05e8a877f0..bf10369cc9 100644 --- a/.github/workflows/docs-preview.yml +++ b/.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: diff --git a/.github/workflows/shared.yml b/.github/workflows/shared.yml index 1dc2692eb1..36ef4f2377 100644 --- a/.github/workflows/shared.yml +++ b/.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" diff --git a/pyproject.toml b/pyproject.toml index 2260ea2e27..e41416b8ac 100644 --- a/pyproject.toml +++ b/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", diff --git a/uv.lock b/uv.lock index e9abba117d..d574f1b089 100644 --- a/uv.lock +++ b/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]