ci(docs): add link-check automation and tighten Docusaurus strictness

.github/workflows/deploy-pages-test.yml

@@ -29,4 +29,21 @@ jobs:
       - name: Install dependencies
         run: yarn install --frozen-lockfile
       - name: Test build website
-        run: yarn build
+        run: yarn build
+
+      - name: Restore lychee cache
+        uses: actions/cache@v4
+        with:
+          path: docs/.lycheecache
+          key: lychee-html-${{ hashFiles('docs/docs/**/*.md', 'docs/docs/**/*.mdx', 'docs/lychee.toml') }}
+          restore-keys: lychee-html-
+
+      - name: Check links in built HTML
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --config ./docs/lychee.toml
+            --no-progress
+            'docs/build/**/*.html'
+          fail: true
+          workingDirectory: ${{ github.workspace }}

.github/workflows/link-check.yml

@@ -0,0 +1,49 @@
+name: Documentation Link Check
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/docs/**'
+      - 'docs/lychee.toml'
+      - '.github/workflows/link-check.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/docs/**'
+      - 'docs/lychee.toml'
+      - '.github/workflows/link-check.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  markdown-links:
+    name: Check links in Markdown sources
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Restore lychee cache
+        uses: actions/cache@v4
+        with:
+          path: .lycheecache
+          key: lychee-markdown-${{ hashFiles('docs/docs/**/*.md', 'docs/docs/**/*.mdx', 'docs/lychee.toml') }}
+          restore-keys: lychee-markdown-
+
+      - name: Run lychee on Markdown sources
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --config ./docs/lychee.toml
+            --no-progress
+            'docs/docs/**/*.md'
+            'docs/docs/**/*.mdx'
+          fail: true

docs/docusaurus.config.ts

@@ -21,6 +21,7 @@ const config: Config = {
   deploymentBranch: 'gh-pages',
 
   onBrokenLinks: 'throw',
+  onBrokenAnchors: 'throw',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -85,7 +86,7 @@ const config: Config = {
   markdown: {
     mermaid: true,
     hooks: {
-      onBrokenMarkdownLinks: 'warn',
+      onBrokenMarkdownLinks: 'throw',
     },
   },
   themes: ['@docusaurus/theme-mermaid'],

docs/lychee.toml

@@ -0,0 +1,32 @@
+# Lychee link-checker configuration. Used by .github/workflows/link-check.yml
+# and the link-check step in .github/workflows/deploy-pages-test.yml.
+# Docs: https://lychee.cli.rs/usage/config/
+
+max_concurrency = 8
+max_retries = 3
+retry_wait_time = 5
+timeout = 20
+user_agent = "Mozilla/5.0 (compatible; lychee-tunit-docs)"
+
+# 429 = rate-limited; the link is fine, just throttled. 200/206 are accepted by default.
+accept = [429]
+
+cache = true
+max_cache_age = "1d"
+
+# Sites that consistently 4xx/5xx automated checks even though the link is correct,
+# plus localhost/loopback.
+exclude = [
+  "^https://github\\.com/thomhurst/TUnit/edit/",   # Docusaurus "edit this page" — generated, may 404 on new docs
+  "^https://www\\.nuget\\.org/packages/",           # NuGet returns 429/403 to bot UAs
+  "^https://stackoverflow\\.com/",                  # Cloudflare bot challenge
+  "^https://github\\.com/sponsors/",                # often 403 to bots
+  "^https://tluma\\.ai/",                           # third-party widget script, not a doc link
+  "^http://localhost",
+  "^https?://127\\.0\\.0\\.1",
+]
+
+exclude_path = [
+  "docs/node_modules",
+  "docs/.docusaurus",
+]