diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 872eb2be80..d079f62d5a 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -10,12 +10,27 @@ build:
       # that have their own Read the Docs projects. Exit code 183 cancels the
       # build and reports success to the Git provider. Scoped to PR builds
       # ("external" versions) because origin/main is only a meaningful diff
-      # base there. Read the Docs strips shell quoting from commands, so the
+      # base there. Compare against the merge base (origin/main...HEAD), not
+      # against the tip of main: a two-dot diff also reports everything that
+      # landed on main after the PR branched, which made every PR that was
+      # behind main build every site. The checkout is shallow, so fetch the
+      # full history first; without a merge base the diff fails and the build
+      # runs, which is the safe default. Read the Docs strips shell quoting from commands, so the
       # exclude pathspecs must use the quote-free :! form, not ':(exclude)'.
+      # The diff is taken against the merge base (origin/main...HEAD), not
+      # against the tip of main: a two-dot diff also reports everything that
+      # landed on main after the PR branched, which made every PR that was
+      # behind main build every site. The checkout is shallow, so fetch the
+      # full history first; without a merge base the diff fails and the build
+      # runs, which is the safe default.
       - |
-        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- :!packages/zarr-metadata :!packages/zarr-indexing;
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ];
         then
-          exit 183;
+          git fetch --quiet --unshallow origin main pull/$READTHEDOCS_VERSION_NAME/head || true;
+          if git diff --quiet origin/main...HEAD -- :!packages/zarr-metadata :!packages/zarr-indexing :!packages/zarr-http-server;
+          then
+            exit 183;
+          fi
         fi
     install:
       - pip install --upgrade pip
diff --git a/changes/4543.misc.md b/changes/4543.misc.md
new file mode 100644
index 0000000000..54be050e61
--- /dev/null
+++ b/changes/4543.misc.md
@@ -0,0 +1 @@
+Fixed the Read the Docs builds of the zarr-indexing, zarr-metadata and zarr-http-server documentation sites, which failed after an unpinned `pymdown-extensions` release, and made pull request builds of those sites skip when the pull request does not change the package.
diff --git a/packages/zarr-http-server/.readthedocs.yaml b/packages/zarr-http-server/.readthedocs.yaml
index 09cf295794..4490a0c3e1 100644
--- a/packages/zarr-http-server/.readthedocs.yaml
+++ b/packages/zarr-http-server/.readthedocs.yaml
@@ -15,10 +15,20 @@ build:
       # to PR builds ("external" versions) because origin/main is only a
       # meaningful diff base there. The shared docs config and header script
       # live outside the package directory but change this site too.
+      # The diff is taken against the merge base (origin/main...HEAD), not
+      # against the tip of main: a two-dot diff also reports everything that
+      # landed on main after the PR branched, which made every PR that was
+      # behind main build every site. The checkout is shallow, so fetch the
+      # full history first; without a merge base the diff fails and the build
+      # runs, which is the safe default.
       - |
-        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- packages/zarr-http-server packages/mkdocs-base.yml packages/source-version.js;
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ];
         then
-          exit 183;
+          git fetch --quiet --unshallow origin main pull/$READTHEDOCS_VERSION_NAME/head || true;
+          if git diff --quiet origin/main...HEAD -- packages/zarr-http-server packages/mkdocs-base.yml packages/source-version.js;
+          then
+            exit 183;
+          fi
         fi
     install:
       - pip install --upgrade pip
diff --git a/packages/zarr-http-server/pyproject.toml b/packages/zarr-http-server/pyproject.toml
index 1d312cf93f..f7a46eda90 100644
--- a/packages/zarr-http-server/pyproject.toml
+++ b/packages/zarr-http-server/pyproject.toml
@@ -70,6 +70,10 @@ docs = [
     "mkdocs-material==9.7.7",
     "mkdocs==1.6.1",
     "mkdocstrings==1.0.6",
+    # pymdown-extensions 12.3 changed the Highlight extension API; mkdocstrings 1.0.6
+    # cannot drive it (Highlight.__init__() missing argument "md"). Match the
+    # version in the repo-root uv.lock until mkdocstrings is bumped everywhere.
+    "pymdown-extensions==11.0.1",
     "mkdocstrings-python==2.0.8",
     "griffe-inherited-docstrings==1.1.3",
     # mkdocstrings uses ruff to format rendered signatures
diff --git a/packages/zarr-http-server/uv.lock b/packages/zarr-http-server/uv.lock
index 673dc54645..77bb5a0baf 100644
--- a/packages/zarr-http-server/uv.lock
+++ b/packages/zarr-http-server/uv.lock
@@ -2156,6 +2156,7 @@ docs = [
     { name = "mkdocs-material" },
     { name = "mkdocstrings" },
     { name = "mkdocstrings-python" },
+    { name = "pymdown-extensions" },
     { name = "ruff" },
 ]
 examples = [
@@ -2186,6 +2187,7 @@ docs = [
     { name = "mkdocs-material", specifier = "==9.7.7" },
     { name = "mkdocstrings", specifier = "==1.0.6" },
     { name = "mkdocstrings-python", specifier = "==2.0.8" },
+    { name = "pymdown-extensions", specifier = "==11.0.1" },
     { name = "ruff", specifier = "==0.16.8" },
 ]
 examples = [
diff --git a/packages/zarr-indexing/.readthedocs.yaml b/packages/zarr-indexing/.readthedocs.yaml
index 4228d267ca..6577440275 100644
--- a/packages/zarr-indexing/.readthedocs.yaml
+++ b/packages/zarr-indexing/.readthedocs.yaml
@@ -15,10 +15,20 @@ build:
       # to PR builds ("external" versions) because origin/main is only a
       # meaningful diff base there. The shared docs config and header script
       # live outside the package directory but change this site too.
+      # The diff is taken against the merge base (origin/main...HEAD), not
+      # against the tip of main: a two-dot diff also reports everything that
+      # landed on main after the PR branched, which made every PR that was
+      # behind main build every site. The checkout is shallow, so fetch the
+      # full history first; without a merge base the diff fails and the build
+      # runs, which is the safe default.
       - |
-        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- packages/zarr-indexing packages/mkdocs-base.yml packages/source-version.js;
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ];
         then
-          exit 183;
+          git fetch --quiet --unshallow origin main pull/$READTHEDOCS_VERSION_NAME/head || true;
+          if git diff --quiet origin/main...HEAD -- packages/zarr-indexing packages/mkdocs-base.yml packages/source-version.js;
+          then
+            exit 183;
+          fi
         fi
     install:
       - pip install --upgrade pip
diff --git a/packages/zarr-indexing/pyproject.toml b/packages/zarr-indexing/pyproject.toml
index da7bee34aa..50a63832ea 100644
--- a/packages/zarr-indexing/pyproject.toml
+++ b/packages/zarr-indexing/pyproject.toml
@@ -61,6 +61,10 @@ docs = [
     "mkdocs-material==9.7.7",
     "mkdocs==1.6.1",
     "mkdocstrings==1.0.6",
+    # pymdown-extensions 12.3 changed the Highlight extension API; mkdocstrings 1.0.6
+    # cannot drive it (Highlight.__init__() missing argument "md"). Match the
+    # version in the repo-root uv.lock until mkdocstrings is bumped everywhere.
+    "pymdown-extensions==11.0.1",
     "mkdocstrings-python==2.0.8",
     "griffe-inherited-docstrings==1.1.3",
     # mkdocstrings uses ruff to format rendered signatures
diff --git a/packages/zarr-indexing/uv.lock b/packages/zarr-indexing/uv.lock
index 1a4a90e2ba..37a98a5694 100644
--- a/packages/zarr-indexing/uv.lock
+++ b/packages/zarr-indexing/uv.lock
@@ -740,6 +740,7 @@ docs = [
     { name = "mkdocs-material" },
     { name = "mkdocstrings" },
     { name = "mkdocstrings-python" },
+    { name = "pymdown-extensions" },
     { name = "ruff" },
 ]
 test = [
@@ -761,6 +762,7 @@ docs = [
     { name = "mkdocs-material", specifier = "==9.7.7" },
     { name = "mkdocstrings", specifier = "==1.0.6" },
     { name = "mkdocstrings-python", specifier = "==2.0.8" },
+    { name = "pymdown-extensions", specifier = "==11.0.1" },
     { name = "ruff", specifier = "==0.16.8" },
 ]
 test = [
diff --git a/packages/zarr-metadata/.readthedocs.yaml b/packages/zarr-metadata/.readthedocs.yaml
index b67e76948c..5e6f993a3e 100644
--- a/packages/zarr-metadata/.readthedocs.yaml
+++ b/packages/zarr-metadata/.readthedocs.yaml
@@ -15,10 +15,20 @@ build:
       # to PR builds ("external" versions) because origin/main is only a
       # meaningful diff base there. The shared docs config and header script
       # live outside the package directory but change this site too.
+      # The diff is taken against the merge base (origin/main...HEAD), not
+      # against the tip of main: a two-dot diff also reports everything that
+      # landed on main after the PR branched, which made every PR that was
+      # behind main build every site. The checkout is shallow, so fetch the
+      # full history first; without a merge base the diff fails and the build
+      # runs, which is the safe default.
       - |
-        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- packages/zarr-metadata packages/mkdocs-base.yml packages/source-version.js;
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ];
         then
-          exit 183;
+          git fetch --quiet --unshallow origin main pull/$READTHEDOCS_VERSION_NAME/head || true;
+          if git diff --quiet origin/main...HEAD -- packages/zarr-metadata packages/mkdocs-base.yml packages/source-version.js;
+          then
+            exit 183;
+          fi
         fi
     install:
       - pip install --upgrade pip
diff --git a/packages/zarr-metadata/pyproject.toml b/packages/zarr-metadata/pyproject.toml
index 31d548bf2a..109f5b48df 100644
--- a/packages/zarr-metadata/pyproject.toml
+++ b/packages/zarr-metadata/pyproject.toml
@@ -56,6 +56,10 @@ docs = [
     "mkdocs-material==9.7.7",
     "mkdocs==1.6.1",
     "mkdocstrings==1.0.6",
+    # pymdown-extensions 12.3 changed the Highlight extension API; mkdocstrings 1.0.6
+    # cannot drive it (Highlight.__init__() missing argument "md"). Match the
+    # version in the repo-root uv.lock until mkdocstrings is bumped everywhere.
+    "pymdown-extensions==11.0.1",
     "mkdocstrings-python==2.0.8",
     "griffe-inherited-docstrings==1.1.3",
     # mkdocstrings uses ruff to format rendered signatures
diff --git a/packages/zarr-metadata/uv.lock b/packages/zarr-metadata/uv.lock
index 07ad9a0ebe..52967144b5 100644
--- a/packages/zarr-metadata/uv.lock
+++ b/packages/zarr-metadata/uv.lock
@@ -773,15 +773,15 @@ wheels = [
 
 [[package]]
 name = "pymdown-extensions"
-version = "12.1"
+version = "11.0.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "markdown" },
     { name = "pyyaml" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/2a/94/858e0163cb4d83d6d8234018a01792c749a56daee41794cac7d6c46661e8/pymdown_extensions-12.1.tar.gz", hash = "sha256:fdb8f47f5d7fd069d10ef2a7d8908e613d7865ff0419d544a0ffd3984e884f11", size = 868245, upload-time = "2026-09-23T00:08:42Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/21/a9/5f0c535ba3b08fe09270c16808e053a968868242ecbd5676d4e3a488bf28/pymdown_extensions-11.0.1.tar.gz", hash = "sha256:dd2905ae6fc5b75582fafb139a1266ffc754705efa902aa50067fa7ff4f94ec0", size = 857113, upload-time = "2026-07-02T17:59:22.955Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/36/d1/98313da89960a604402266a115311b510254900ff1295ea426403f9423cc/pymdown_extensions-12.1-py3-none-any.whl", hash = "sha256:4a254b771acfcddc6c110a7f4590d818f1f849e2d5aacf69b4b07c8dd2a9700d", size = 277069, upload-time = "2026-09-23T00:08:40.069Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/54/da572c98c0b77626a91b5d3b89f0231d8bff5125c225420908632f8b342d/pymdown_extensions-11.0.1-py3-none-any.whl", hash = "sha256:db3943a62bab7e03af1364f0c4083e64b91fb097675a4b6cceccfbe9a77e5eb2", size = 269455, upload-time = "2026-07-02T17:59:21.271Z" },
 ]
 
 [[package]]
@@ -1145,6 +1145,7 @@ docs = [
     { name = "mkdocs-material" },
     { name = "mkdocstrings" },
     { name = "mkdocstrings-python" },
+    { name = "pymdown-extensions" },
     { name = "ruff" },
 ]
 test = [
@@ -1164,6 +1165,7 @@ docs = [
     { name = "mkdocs-material", specifier = "==9.7.7" },
     { name = "mkdocstrings", specifier = "==1.0.6" },
     { name = "mkdocstrings-python", specifier = "==2.0.8" },
+    { name = "pymdown-extensions", specifier = "==11.0.1" },
     { name = "ruff", specifier = "==0.16.8" },
 ]
 test = [