chore: improve links and markdownlint workflows

links.yml:
- Add timeout-minutes and persist-credentials
- Switch to split cache/restore pattern with static key
- Add duplicate issue prevention (comment on existing vs create new)
- Use multi-line YAML for lychee args

markdownlint.yml:
- Add timeout-minutes and persist-credentials
- Trigger on .markdownlint.json config changes
- Pin markdownlint-cli2 to 0.20.0

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: sjnims

.github/workflows/links.yml

@@ -4,15 +4,15 @@ name: Check Links
 # Key flags:
 #   --cache: Cache results to speed up subsequent runs
 #   --exclude-link-local: Skip localhost/127.0.0.1 links (not reachable in CI)
-#   --exclude-file: Use .lycheeignore for links that shouldn't be checked (e.g., rate-limited sites)
+# .lycheeignore is auto-detected for URL patterns to exclude
 # Creates a GitHub issue on failure for visibility
 
 on:
   pull_request:
     paths:
-      - '**.md'
+      - "**.md"
   schedule:
-    - cron: '0 0 * * 0'  # Weekly on Sunday at midnight UTC
+    - cron: "0 0 * * 0" # Weekly on Sunday at midnight UTC
   workflow_dispatch:
 
 concurrency:
@@ -21,33 +21,79 @@ concurrency:
 
 permissions:
   contents: read
-  issues: write  # Required by peter-evans/create-issue-from-file on failure
+  issues: write # Required for creating issue on failure
 
 jobs:
   linkChecker:
     name: Check Markdown Links
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
+      # Static key: lychee handles staleness via --max-cache-age 1d
+      # Split restore/save pattern ensures cache is saved even on failure
       - name: Restore lychee cache
-        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
+        id: restore-cache
+        uses: actions/cache/restore@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
         with:
           path: .lycheecache
-          key: cache-lychee-${{ github.sha }}
-          restore-keys: cache-lychee-
+          key: cache-lychee-v1
 
       - name: Link Checker
         uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2.7.0
         with:
-          args: --cache --max-cache-age 1d --verbose --no-progress --exclude-link-local --exclude-file .lycheeignore '**/*.md'
+          args: >-
+            --cache
+            --max-cache-age 1d
+            --verbose
+            --no-progress
+            --exclude-link-local
+            '**/*.md'
           fail: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Create Issue From File
+      - name: Save lychee cache
+        uses: actions/cache/save@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
+        if: always()
+        with:
+          path: .lycheecache
+          key: cache-lychee-v1
+
+      # Check for existing issue to avoid duplicates, then create or comment
+      - name: Check for existing open issue
         if: failure()
+        id: check-issue
+        run: |
+          issue=$(gh issue list --state open \
+            --search "in:title Broken links detected" \
+            --json number --jq '.[0].number // empty')
+          echo "issue_number=$issue" >> "$GITHUB_OUTPUT"
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create issue for broken links
+        if: failure() && steps.check-issue.outputs.issue_number == ''
         run: gh issue create --title "Broken links detected" --body-file ./lychee/out.md
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Comment on existing issue
+        if: failure() && steps.check-issue.outputs.issue_number != ''
+        run: |
+          run_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${RUN_ID}"
+          {
+            echo "## 🔄 Link check failed again"
+            echo ""
+            echo "**Run**: [${RUN_ID}](${run_url})"
+            echo "**Triggered by**: ${GITHUB_EVENT_NAME}"
+            echo ""
+            cat ./lychee/out.md
+          } | gh issue comment "${{ steps.check-issue.outputs.issue_number }}" --body-file -
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RUN_ID: ${{ github.run_id }}

.github/workflows/markdownlint.yml

@@ -4,11 +4,13 @@ on:
   pull_request:
     paths:
       - "**.md"
+      - ".markdownlint.json"
   push:
     branches:
       - main
     paths:
       - "**.md"
+      - ".markdownlint.json"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -21,9 +23,12 @@ jobs:
   lint:
     name: Lint Markdown Files
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
 
       - name: Run markdownlint
-        run: npx markdownlint-cli2 "**/*.md" "#node_modules"
+        run: npx markdownlint-cli2@0.20.0 "**/*.md" "#node_modules"