ci(docs): 🔗 add docs link check

.github/workflows/docpages.yml

@@ -76,6 +76,16 @@ jobs:
         run: |
           just build-docs
 
+      - 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
+            '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,18 @@
+# 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.
+# Also some websites like aps.org block crawlers with 403.
+accept = [200, 403, 429]
+
+# False positives:
+# - localhost:3000: development server URL used as an example in the docs.
+exclude = [
+  "^http://localhost",
+]

.lychee.toml

@@ -0,0 +1,14 @@
+# 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.
+# /benchmarks/* images live in docs/public/ and are served at runtime; they cannot be resolved as
+# local file paths by lychee.
+exclude = [
+  "^/api(?:$|/)",
+  "file://.*/docs/content/docs/api(?:$|[#/])",
+  "^/benchmarks/",
+]

README.md

@@ -175,6 +175,7 @@ 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 exported HTML links (including external URLs)
 ```
 
 ### Keeping documentation up to date

docs/content/docs/benchmarks.mdx

@@ -182,7 +182,7 @@ The end-to-end workflow is:
 
 #### 1. Choose the simulation settings
 
-All simulation parameters live in [`settings.json`](settings.json) and are shared by every engine
+All simulation parameters live in [`settings.json`](https://github.com/Algorithmiq/monoprop/blob/main/packages/bench-third-party/pauli_prop/settings.json) and are shared by every engine
 (Python and Julia alike), so a single edit compares them all on an identical problem instance:
 
 | Key          | Meaning                                                                               |

justfile

@@ -206,6 +206,10 @@ doctest-docs:
 build-docs: docs-install gen-api doctest-py doctest-docs gen-notebooks
     cd {{ site }} && npm run build
 
+# Check exported HTML links (including external URLs).
+check-doc-links:
+    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