ci(docs): 🔗 add source and post-build docs link checks

.github/workflows/docpages.yml

@@ -77,6 +77,26 @@ jobs:
         run: |
           just build-docs
 
+      - name: Check docs internal links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --config .lychee.toml --no-progress
+            --root-dir ${{ github.workspace }}/docs/content/docs
+            --fallback-extensions mdx,md --index-files index.mdx,index.md
+            'docs/content/docs/**/*.mdx' docs/README.md README.md
+          fail: true
+
+      - name: Check built docs links (including external)
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --config .lychee.postbuild.toml --no-progress
+            --root-dir ${{ github.workspace }}/docs/out
+            --fallback-extensions html --index-files index.html
+            'docs/out/**/*.html'
+          fail: true
+
       - name: Setup Pages
         if: ${{ github.ref == 'refs/heads/main' }}
         uses: actions/configure-pages@v6.0.0

.lychee.postbuild.toml

@@ -0,0 +1,11 @@
+# Post-build check over exported HTML with external links enabled.
+
+# Avoid noisy/generated dependency paths if ever passed as inputs.
+exclude_path = ["docs/node_modules/**"]
+
+# Keep retries bounded while reducing transient external failures.
+max_retries = 2
+timeout = 20
+
+# Treat common external rate limiting as non-fatal for CI stability.
+accept = [200, 429]

.lychee.toml

@@ -0,0 +1,8 @@
+# Restrict checks to local repository links/anchors.
+offline = true
+
+# Avoid traversing generated and dependency directories if they appear in inputs.
+exclude_path = ["docs/out/**", "docs/node_modules/**"]
+
+# API docs are generated by `just gen-api`; skip this route in source-only checks.
+exclude = ["^/api(?:$|/)", "file://.*/docs/content/docs/api(?:$|[#/])"]

README.md

@@ -142,8 +142,13 @@ executed from the notebooks in `docs/notebooks/`.  Building the documentation lo
 ```bash
 just build-docs   # output: docs/out/
 just serve-docs   # live-reloading dev server
+just check-doc-links  # checks internal docs links/anchors from source MDX
+just check-doc-links-built  # builds docs and checks exported HTML links (including external URLs)
 ```
 
+`just check-doc-links` requires [`lychee`](https://github.com/lycheeverse/lychee)
+to be installed locally.
+
 ### Keeping documentation up to date
 
 Any PR that changes behavior, public APIs, build/test commands, or repository paths

justfile

@@ -139,6 +139,14 @@ doctest-docs:
 build-docs: docs-install gen-api doctest-py doctest-docs gen-notebooks
     cd {{ site }} && npm run build
 
+# Check docs for broken internal links and anchors.
+check-doc-links:
+    lychee --config .lychee.toml --root-dir "{{ project_source_dir }}/docs/content/docs" --fallback-extensions mdx,md --index-files index.mdx,index.md 'docs/content/docs/**/*.mdx' docs/README.md README.md
+
+# Build docs, then check exported HTML links (including external URLs).
+check-doc-links-built: build-docs
+    lychee --config .lychee.postbuild.toml --root-dir "{{ project_source_dir }}/docs/out" --fallback-extensions html --index-files index.html 'docs/out/**/*.html'
+
 # Serve the documentation locally with hot reloading.
 serve-docs:
     cd {{ site }} && npm run dev