link checker - fails PR if links are broken

.github/actions/markdown-link-checker/action.yaml

@@ -0,0 +1,49 @@
+name: Markdown Link Checker
+description: Checks all Markdown files for broken links
+inputs:
+  github-token:
+    description: GitHub token (not used, but kept for interface compatibility)
+    required: false
+  args:
+    description: Arguments to pass to markdown-link-check
+    required: false
+    default: "--quiet --retry"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install markdown-link-check
+      shell: bash
+      run: npm install -g markdown-link-check
+
+    - name: Run link check on all Markdown files
+      shell: bash
+      run: |
+        set -euo pipefail
+        echo "🔍 Scanning all Markdown files for broken links..."
+        failed=0
+        total_dead_links=0
+
+        while IFS= read -r -d '' file; do
+          echo "------------------------------------------------------------"
+          echo "📄 Checking: $file"
+          output=$(markdown-link-check ${{ inputs.args }} "$file" 2>&1)
+          echo "$output"
+
+          if echo "$output" | grep -q '✖'; then
+            num_file_dead_links=$(echo "$output" | grep '✖' | wc -l)
+            echo "❌ $num_file_dead_links broken links in $file"
+            total_dead_links=$((total_dead_links + num_file_dead_links))
+            failed=1
+          else
+            echo "✅ No broken links in $file"
+          fi
+        done < <(find . -type f -name "*.md" -print0)
+
+        echo "------------------------------------------------------------"
+        if [ "$failed" -ne 0 ]; then
+          echo "❌ Total broken links found: $total_dead_links"
+          exit 1
+        else
+          echo "✅ All Markdown files passed link checks."
+        fi

.github/workflows/ci-pr-checks.yaml

@@ -28,6 +28,12 @@ jobs:
       - name: go mod tidy
         run: go mod tidy
 
+      - name: Run markdown link checker
+        uses: ./.github/actions/markdown-link-checker
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          args: "--quiet --retry"  
+
       - name: Run lint checks
         uses: golangci/golangci-lint-action@v8
         with: