ci: add markdown lint and link check workflows with configs (P3-21)

Author: pidster

.github/workflows/docs-lint.yml

@@ -0,0 +1,32 @@
+name: Docs Lint & Links
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run markdownlint-cli2
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          globs: |
+            **/*.md
+          config: .markdownlint.jsonc
+
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run lychee link checker
+        uses: lycheeverse/lychee-action@v1
+        with:
+          args: |
+            --config .lychee.toml \
+            --verbose \
+            **/*.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.lychee.toml

@@ -0,0 +1,22 @@
+# Lychee link checker configuration
+# See https://github.com/lycheeverse/lychee
+
+# Exclude common transient or rate-limited hosts
+exclude = [
+  "https://img.shields.io/",
+  "https://badgen.net/",
+  "https://github.com/capgemini/template-github-copilot/actions",
+]
+
+# Accept 429/403 as warnings instead of failures for rate-limited hosts
+accept = [429, 403]
+
+# Request options
+user_agent = "lychee-link-checker"
+max_concurrency = 20
+
+# Treat mailto and anchors as valid without network requests
+accept_pattern = [
+  "^mailto:",
+  "^#",
+]

.markdownlint.jsonc

@@ -0,0 +1,21 @@
+{
+  // General rules
+  "default": true,
+
+  // Allow long lines in docs for readability tables/links (disable MD013)
+  "MD013": false,
+
+  // Allow inline HTML for badges and diagrams (MD033)
+  "MD033": {
+    "allowed_elements": ["img", "br", "a", "details", "summary"]
+  },
+
+  // Require first heading to be a top-level H1
+  "MD002": true,
+
+  // Disallow trailing spaces except in code blocks
+  "MD009": { "br_spaces": 0 },
+
+  // Enforce consistent unordered list markers
+  "MD004": { "style": "dash" }
+}