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