ci(docs): pin MkDocs dependencies and improve workflow reproducibility

- Add docs/requirements.txt with pinned versions of MkDocs, Material
  theme, and plugins to ensure reproducible builds locally and in CI
- Update docs workflow to install deps from requirements.txt instead of
  inline package names, and wire `cache-dependency-path` to the new
  file so pip cache hits are deterministic
- Bump actions/upload-pages-artifact and actions/deploy-pages to v5
- Add `_mkdocs/` to the SOURCE_DIR_PREFIXES exclusion list in hooks.py
- Add pyenv and venv to the cspell dictionary
- Minor formatting fixes (branch list spacing, comment alignment)

Author: hyp3rd

.github/workflows/docs.yml

@@ -17,7 +17,7 @@ on:
       - "cmd/hypercache-server/README.md"
       - ".github/workflows/docs.yml"
   push:
-    branches: [main]
+    branches: [ main ]
     paths:
       - "docs/**"
       - "mkdocs.yml"
@@ -48,20 +48,23 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          fetch-depth: 0   # docs/ may reference files via relative paths
+          fetch-depth: 0  # docs/ may reference files via relative paths
 
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
           python-version: "3.13"
           cache: pip
+          # `actions/setup-python` uses this file's hash as the
+          # pip-cache key. docs/requirements.txt pins the MkDocs
+          # + plugin versions so cache hits are reproducible and
+          # the runner can find a key file at all.
+          cache-dependency-path: docs/requirements.txt
 
       - name: Install MkDocs + plugins
         run: |
           python -m pip install --upgrade pip
-          pip install mkdocs-material \
-                      mkdocs-include-markdown-plugin \
-                      mkdocs-glightbox
+          pip install -r docs/requirements.txt
 
       - name: Build site (strict)
         # Strict in CI catches broken links / missing pages on PR;
@@ -70,7 +73,7 @@ jobs:
 
       - name: Upload Pages artifact
         if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: ./site
 
@@ -86,4 +89,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

_mkdocs/hooks.py

@@ -51,6 +51,7 @@
     "__examples/",
     ".github/",
     "docker/",
+    "_mkdocs/",
 )
 
 LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")

cspell.config.yaml

@@ -174,6 +174,7 @@ words:
   - protoc
   - pushd
   - pygments
+  - pyenv
   - pymdownx
   - recvcheck
   - rediscluster
@@ -219,6 +220,7 @@ words:
   - upserted
   - upserts
   - varnamelen
+  - venv
   - vettool
   - vnode
   - vnodes

docs/requirements.txt

@@ -0,0 +1,20 @@
+# Pinned dependency set for the MkDocs site build. Used by both
+# `make docs-build` (via the operator's pyenv `mkdocs` venv) and
+# `.github/workflows/docs.yml` (via actions/setup-python with
+# `cache: pip` — the file's hash is the cache key, so pinned
+# versions also produce reproducible cache hits).
+#
+# Bump deliberately: the Material theme moves fast and changes
+# can shift visual output. Verify with `mkdocs build --strict`
+# locally before bumping.
+
+
+# Transitive deps that Material relies on. Pinned for the same
+# reproducibility reason as the plugins above.
+Markdown==3.10.2
+mkdocs==1.6.1
+mkdocs-glightbox==0.5.2
+mkdocs-include-markdown-plugin==7.2.2
+mkdocs-material==9.7.6
+mkdocs-material-extensions==1.3.1
+Pygments==2.20.0