ci: guard docs drift — mkdocs --strict as a PR check + link/anchor validation

Adds a parallel docs job running mkdocs --strict on PRs (matching the deploy
build), a validation block so broken internal links/anchors and orphaned pages
fail the build, and upper-bound pins on the docs toolchain.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lesnik512

.github/workflows/_checks.yml

@@ -16,6 +16,14 @@ jobs:
       - run: uv python pin 3.11
       - run: just install lint-ci
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: extractions/setup-just@v4
+      - uses: astral-sh/setup-uv@v8.2.0
+      - run: just docs-build
+
   pytest:
     runs-on: ubuntu-latest
     strategy:

docs/requirements.txt

@@ -1,2 +1,2 @@
-mkdocs
-mkdocs-material
+mkdocs>=1.6,<2
+mkdocs-material>=9,<10

mkdocs.yml

@@ -50,6 +50,12 @@ theme:
 extra_css:
   - css/brand.css
 
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn
+
 markdown_extensions:
   - toc:
       permalink: true