ci(docs): add lychee link check and markdownlint workflows with config

Author: srnichols

.github/workflows/link-check.yml

@@ -0,0 +1,49 @@
+name: Docs Link Check
+
+on:
+  pull_request:
+    branches: [ master ]
+    paths:
+      - '**/*.md'
+      - '.github/workflows/link-check.yml'
+      - 'lychee.toml'
+  workflow_dispatch: {}
+
+concurrency:
+  group: link-check-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lychee:
+    name: Check links with lychee
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run lychee link checker
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # Respect config file settings; output summary and fail on broken links
+          args: >-
+            --config lychee.toml
+            --no-progress
+            --max-redirects 10
+            --timeout 20
+            --retry-wait-time 2
+            --max-retries 2
+            --format detailed
+            --exclude-mail
+            **/*.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload lychee report (always)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: lychee-report
+          path: |
+            lychee-out.md
+            lychee-out.txt
+            lychee-cache*

.github/workflows/markdownlint.yml

@@ -0,0 +1,38 @@
+name: Markdown Lint
+
+on:
+  pull_request:
+    branches: [ master ]
+    paths:
+      - '**/*.md'
+      - '.github/workflows/markdownlint.yml'
+      - '.markdownlint.jsonc'
+  push:
+    branches: [ master ]
+    paths:
+      - '.markdownlint.jsonc'
+  workflow_dispatch: {}
+
+concurrency:
+  group: mdlint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install markdownlint-cli2
+        run: |
+          npm install -g markdownlint-cli2
+
+      - name: Run markdownlint
+        run: |
+          markdownlint-cli2 "**/*.md" "!**/bin/**" "!**/obj/**" || exit 1

.markdownlint.jsonc

@@ -0,0 +1,28 @@
+{
+  // Base rules
+  "default": true,
+
+  // Line length: allow long URLs/tables
+  "MD013": false,
+
+  // Multiple headings with same content are OK in long guides
+  "MD024": false,
+
+  // Allow inline HTML (for mermaid, badges, etc.)
+  "MD033": false,
+
+  // Allow duplicate headers across files
+  "MD025": {
+    "level": 1,
+    "front_matter_title": "^$"
+  },
+
+  // Require blank line before/after lists for readability
+  "MD032": true,
+
+  // Emphasis used sparingly; allow current style
+  "MD036": false,
+
+  // Links: allow reference-style or inline
+  "MD011": true
+}

lychee.toml

@@ -0,0 +1,35 @@
+# lychee configuration for docs link checking
+# See https://github.com/lycheeverse/lychee for options
+
+# Inputs are passed via action arguments (/**/*.md)
+
+# Cache to speed up repeated runs
+cache = true
+max_cache_age = "2d"
+
+# Treat HTTP 429 as a warning by retrying and not failing the job
+retry_wait_time = 2
+max_retries = 2
+
+# Timeouts
+timeout = 20
+
+# Exclusions: private/internal or known transient domains
+exclude = [
+  "mailto:",
+  "^#",                     # page anchors handled by renderer
+  "https://aka.ms/.*",      # shortlinks often redirect
+  "https://help.github.com/.*",
+]
+
+# Accept some status codes as valid (e.g., 429 throttling)
+accept = [200, 201, 202, 203, 204, 206, 300, 301, 302, 303, 307, 308]
+
+# GitHub API token for rate limits (provided by action)
+[github]
+# use token from env
+
+# Output report files
+[output]
+format = "detailed"
+save = "lychee-out.txt"