From c03f89a53d087dc2e915a44f2e7a66c87a1ef603 Mon Sep 17 00:00:00 2001
From: Artur Shiriev <lesnik512@gmail.com>
Date: Mon, 29 Jun 2026 00:04:02 +0300
Subject: [PATCH] build: pin mkdocs<2 to stay clear of the MkDocs 2.0 rewrite

MkDocs 2.0 is a backward-incompatible rewrite (no plugin system, no theme
overrides, no migration path) that breaks Material for MkDocs. Material 9.7.5+
already caps mkdocs<2; make that explicit and bump the Material floor so a fresh
resolve can never pull MkDocs 2.0. Docs continue to build on mkdocs 1.6.1 /
mkdocs-material 9.7.6.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 pyproject.toml | 8 +++++++-
 uv.lock        | 6 +++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 86f2fa9..398e332 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,13 @@ version = "0"
 description = "modern-python.org organization homepage"
 requires-python = ">=3.11"
 dependencies = [
-    "mkdocs-material>=9.5",
+    # MkDocs 2.0 is a backward-incompatible rewrite (no plugin system, no theme
+    # overrides) that breaks Material for MkDocs, with no migration path. Material
+    # 9.7.5+ already caps mkdocs<2; pin both explicitly so a fresh resolve can
+    # never pull MkDocs 2.0.
+    # https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.7.5",
 ]
 
 [dependency-groups]
diff --git a/uv.lock b/uv.lock
index 04bae8e..5f8fa19 100644
--- a/uv.lock
+++ b/uv.lock
@@ -400,6 +400,7 @@ name = "modern-python-org"
 version = "0"
 source = { virtual = "." }
 dependencies = [
+    { name = "mkdocs" },
     { name = "mkdocs-material" },
 ]
 
@@ -410,7 +411,10 @@ dev = [
 ]
 
 [package.metadata]
-requires-dist = [{ name = "mkdocs-material", specifier = ">=9.5" }]
+requires-dist = [
+    { name = "mkdocs", specifier = ">=1.6,<2" },
+    { name = "mkdocs-material", specifier = ">=9.7.5" },
+]
 
 [package.metadata.requires-dev]
 dev = [