From 769ede175079c749eda7ca4097845c7c66f719aa Mon Sep 17 00:00:00 2001
From: Henrik Andersson <jan@dhigroup.com>
Date: Mon, 18 May 2026 16:54:23 +0200
Subject: [PATCH] docs: add lychee link-check recipes

A full quarto render takes minutes, so iterating on broken links is
painful. Add three `just` recipes backed by lychee:

- `linkcheck` checks .qmd sources offline (fast, no render).
- `linkcheck-site` renders with `--no-execute` (skips Python cells) and
  checks the resulting `_site/`. Catches quartodoc-generated cross-refs
  and missing anchors that source-only checks can't see.
- `linkcheck-online` adds external URL checks.

Document the install in CONTRIBUTING.
---
 CONTRIBUTING.md | 10 ++++++++++
 justfile        | 21 +++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 84091161f..66390e45a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -28,6 +28,16 @@ uv sync --group docs
 make docs
 ```
 
+### Checking links
+
+A full doc render takes minutes. To validate links faster, install [lychee](https://lychee.cli.rs/) (`brew install lychee`, `cargo install lychee`, or grab a binary from the [releases page](https://github.com/lycheeverse/lychee/releases)), then:
+
+```bash
+just linkcheck         # .qmd sources, offline (no render needed)
+just linkcheck-site    # render with --no-execute, then check rendered HTML (catches quartodoc cross-refs and anchors)
+just linkcheck-online  # .qmd sources + external URLs
+```
+
 ## Running specific tests
 
 ```bash
diff --git a/justfile b/justfile
index d027887a5..9e609ca57 100644
--- a/justfile
+++ b/justfile
@@ -42,6 +42,27 @@ docs:
     cd docs; uv run quartodoc build; uv run quarto render
     if (!(Test-Path docs/_site/index.html)) { Write-Error "Error: index.html not found."; exit 1 }
 
+# Build docs without executing Python (fast; produces a link-checkable _site/)
+[unix]
+docs-fast:
+    cd docs && uv run quartodoc build && uv run quarto render --no-execute
+
+[windows]
+docs-fast:
+    cd docs; uv run quartodoc build; uv run quarto render --no-execute
+
+# Check links in .qmd sources (offline, no render needed)
+linkcheck:
+    lychee --offline --include-fragments 'docs/**/*.qmd'
+
+# Check links in rendered site (catches quartodoc cross-refs and anchors)
+linkcheck-site: docs-fast
+    lychee --offline --include-fragments 'docs/_site/**/*.html'
+
+# Check external URLs in .qmd sources (hits the network)
+linkcheck-online:
+    lychee --include-fragments 'docs/**/*.qmd'
+
 # Clean build artifacts
 [unix]
 clean: