From 089242225e1da3b19429e731194bea6f8b61ade1 Mon Sep 17 00:00:00 2001
From: "Matteo A.C. Rossi" <matteo@algorithmiq.fi>
Date: Fri, 10 Jul 2026 17:44:21 +0300
Subject: [PATCH] =?UTF-8?q?ci(docs):=20=F0=9F=94=97=20add=20source=20and?=
 =?UTF-8?q?=20post-build=20link=20checks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add lychee-based docs link checking for both source MDX (internal links) and built HTML output (including external links), and wire both checks into the documentation workflow. Update docs commands in README accordingly.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/docpages.yml | 20 ++++++++++++++++++++
 .lychee.postbuild.toml         | 11 +++++++++++
 .lychee.toml                   |  8 ++++++++
 README.md                      |  5 +++++
 justfile                       |  8 ++++++++
 5 files changed, 52 insertions(+)
 create mode 100644 .lychee.postbuild.toml
 create mode 100644 .lychee.toml

diff --git a/.github/workflows/docpages.yml b/.github/workflows/docpages.yml
index d400b358..149591bc 100644
--- a/.github/workflows/docpages.yml
+++ b/.github/workflows/docpages.yml
@@ -91,6 +91,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
diff --git a/.lychee.postbuild.toml b/.lychee.postbuild.toml
new file mode 100644
index 00000000..f92f48ff
--- /dev/null
+++ b/.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]
diff --git a/.lychee.toml b/.lychee.toml
new file mode 100644
index 00000000..54d8d304
--- /dev/null
+++ b/.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(?:$|[#/])"]
diff --git a/README.md b/README.md
index 66836871..50d34ed5 100644
--- a/README.md
+++ b/README.md
@@ -115,8 +115,13 @@ executed from the notebooks in `docs/notebooks/`. To build it locally:
 ```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.
+
 ## Citation
 
 If you use `monoprop` in your research, please cite:
diff --git a/justfile b/justfile
index c376d343..ee6fe32b 100644
--- a/justfile
+++ b/justfile
@@ -110,6 +110,14 @@ doctest-py:
 build-docs: docs-install gen-api doctest-py 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: docs-install gen-api gen-notebooks
     cd {{ site }} && npm run dev