Link checker

Author: fildon

.github/workflows/link-check.yml

@@ -0,0 +1,67 @@
+name: Link Check
+
+on:
+  # Run monthly to catch link rot
+  schedule:
+    - cron: '0 0 1 * *' # First day of each month at midnight
+  # Also run on workflow_dispatch so you can trigger manually
+  workflow_dispatch:
+  # Run on PRs to catch broken links before merging
+  pull_request:
+    paths:
+      - 'src/**/*.md'
+      - 'src/**/*.njk'
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        run: npm run build
+
+      - name: Check links
+        uses: lycheeverse/lychee-action@v1
+        with:
+          # Check all HTML files in the built site
+          args: --verbose --no-progress './_site/**/*.html'
+          # Fail the workflow if broken links are found
+          fail: true
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+
+      - name: Create Issue on failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = '🔗 Broken links detected';
+            const body = `The scheduled link check found broken links.\n\nCheck the [workflow run](${context.payload.repository.html_url}/actions/runs/${context.runId}) for details.`;
+            
+            // Check if an issue already exists
+            const issues = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: ['broken-links']
+            });
+            
+            if (issues.data.length === 0) {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: title,
+                body: body,
+                labels: ['broken-links']
+              });
+            }

.gitignore

@@ -4,3 +4,6 @@ _site
 node_modules
 
 .DS_Store
+
+# Link checker cache
+.lycheecache

.markdownlint.json

@@ -1,4 +1,6 @@
 {
   "MD013": false,
-  "MD033": false
+  "MD033": false,
+  "default": true,
+  "ignores": ["**/*.toml", "LICENSE"]
 }

README.md

@@ -29,6 +29,18 @@ The development server includes:
 
 Having produced a build in `_site`, the entire directory is pushed up on a `gh-pages` branch to GitHub, and hosted exactly as-is.
 
+## Quality Assurance
+
+### Link Checking
+
+The repository includes automated link checking via GitHub Actions:
+
+- **Scheduled checks**: Runs monthly to catch link rot
+- **PR checks**: Validates links in pull requests
+- **Manual trigger**: Can be run on-demand from the Actions tab
+
+Configuration is in `lychee.toml`. If broken links are found, an issue will be automatically created with the `broken-links` label.
+
 ## Publishing a new blog post
 
 A new blog post should be authored within the `/src/blog` directory. It should have its own subdirectory. The name of the subdirectory will become the URL route, e.g. `/src/blog/42-foo/index.md` will become `rupertmckay.com/blog/42-foo`. I maintain a convention of prefixing the directories with a number in order to keep the directories chronologically ordered in the source code. The markdown file must be named `index.md` or else its name will be appended to the route URL, e.g. `/src/blog/42-foo/foo.md` will become `rupertmckay.com/blog/42-foo/foo`, which we don't want.

lychee.toml

@@ -0,0 +1,41 @@
+# Lychee link checker configuration
+# https://github.com/lycheeverse/lychee
+
+# Maximum number of concurrent network requests
+max_concurrency = 8
+
+# Check links in HTML
+include = ["./**/*.html"]
+
+# Exclude patterns (regex)
+exclude = [
+  # Exclude localhost and local IPs
+  "http://localhost",
+  "http://127.0.0.1",
+  "http://0.0.0.0",
+  
+  # Exclude common patterns that might be examples
+  "http://example.com",
+  "https://example.com",
+  
+  # Exclude mailto links (they often fail checks)
+  "mailto:",
+]
+
+# Accepted status codes for valid links
+accept = [200, 201, 202, 203, 204, 206, 300, 301, 302, 303, 304, 307, 308, "999"]
+
+# Follow redirects
+max_redirects = 10
+
+# Timeout in seconds for network requests
+timeout = 20
+
+# User agent
+user_agent = "Mozilla/5.0 (compatible; LinkChecker/1.0)"
+
+# Exclude private network addresses
+exclude_private = true
+
+# Don't check links that are already cached (speeds up repeat checks)
+cache = true