From 95e7ff9b8b730f0986d5bd5a7aec39a72c6ef948 Mon Sep 17 00:00:00 2001
From: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Date: Tue, 7 Jul 2026 12:47:27 +0000
Subject: [PATCH] [v1.x] docs: pin mkdocs<2

MkDocs 2.0 is a ground-up rewrite that drops the plugin system, so it is
incompatible with mkdocs-material and the rest of the docs plugin stack.
Mirror the bound from main (#3072) on the direct dependency so a future
re-lock on this branch cannot resolve 2.0. The locked versions are
unchanged; today the branch is protected only transitively by
mkdocs-material 9.6.x's own mkdocs~=1.6 requirement.
---
 pyproject.toml | 4 +++-
 uv.lock        | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 8611f5c4b6..9a4cf051ef 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -69,7 +69,9 @@ dev = [
     "coverage[toml]==7.10.7",
 ]
 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-glightbox>=0.4.0",
     "mkdocs-material[imaging]>=9.6.19",
     "mkdocstrings-python>=1.12.2",
diff --git a/uv.lock b/uv.lock
index 43e6218c0b..031ba38f04 100644
--- a/uv.lock
+++ b/uv.lock
@@ -865,7 +865,7 @@ dev = [
     { name = "trio", specifier = ">=0.26.2" },
 ]
 docs = [
-    { name = "mkdocs", specifier = ">=1.6.1" },
+    { name = "mkdocs", specifier = ">=1.6.1,<2" },
     { name = "mkdocs-glightbox", specifier = ">=0.4.0" },
     { name = "mkdocs-material", extras = ["imaging"], specifier = ">=9.6.19" },
     { name = "mkdocstrings-python", specifier = ">=1.12.2" },