em-jones/link-checker

Link Checker Skill

This skill provides systematic workflows for finding and fixing broken links in your codebase using the lychee link checker. Lychee is a fast, async link checker written in Rust that can scan entire directory trees and output structured JSON for automated processing.

When to Use This Skill

• Automated link validation in CI/CD pipelines
• Periodic documentation health checks
• Before publishing documentation releases
• Post-refactoring verification (after moving or renaming files)
• Finding dead external references to maintain SEO and user experience
• Integration with documentation review workflows

Installation

Ensure lychee is available in your environment:

# Via cargo (Rust)
cargo install lychee

# Via devbox (recommended)
echo "packages = [\"lychee\"]" >> devbox.json
devbox shell

# Via Homebrew (macOS)
brew install lychee

Verify installation:

lychee --version

Workflow Overview

1. Scan — Run lychee with --format json to collect all link data
2. Analyze — Parse JSON output with jq to categorize broken links
3. Filter — Distinguish between dead external links and broken internal paths
4. Fix — Update broken links, redirect references, or add exceptions
5. Verify — Re-scan to confirm all fixes are correct

---

Step 1: Scan for Broken Links

Basic Scan

Scan a directory tree for broken links:

lychee <directory>/**/*.{md,mdx,html,rst} --format json > link-report.json

Common file extensions to scan

| Extension | Type | Use case | | ---------------------------- | --------------------- | ---------------------------------------- | | .md, .mdx | Markdown | Documentation, READMEs, change artifacts | | .html | HTML | Static sites, generated documentation | | .rst | reStructuredText | Sphinx documentation | | .go | Go source | Doc comments, URLs in strings (limited) | | .ts, .tsx, .js, .jsx | TypeScript/JavaScript | Doc comments, URLs in objects |

Scan with timeout and retries

For robust link checking (especially useful for external links):

lychee \
  <directory>/**/*.md \
  --timeout 30 \
  --retry-wait-time 1 \
  --max-retries 3 \
  --format json > link-report.json

Exclude directories and patterns

Skip slow-to-scan or irrelevant directories:

lychee \
  <directory>/**/*.md \
  --exclude "node_modules|.git|.devbox" \
  --exclude-path "./vendor/*" \
  --format json > link-report.json

Skip external links (internal-only scan)

When you only want to find broken internal paths:

lychee \
  <directory>/**/*.md \
  --offline \
  --format json > link-report.json

The --offline flag skips HTTP requests; lychee only validates file paths.

---

Step 2: Analyze the JSON Output

Lychee outputs a JSON object with this structure:

{
  "status": "success",
  "stats": {
    "total": 150,
    "successful": 140,
    "errors": 10,
    "warnings": 0,
    "timeouts": 0
  },
  "failures": [
    {
      "uri": "https://example.com/broken-page",
      "source": "docs/guide.md:42",
      "status": "Error fetching https://example.com/broken-page",
      "code": 404
    },
    {
      "uri": "./relative/path/file.md",
      "source": "docs/overview.md:15",
      "status": "FileNotFound",
      "code": null
    }
  ]
}

Key fields:

• failures[] — Array of broken links
• uri — The link itself (URL or file path)
• source — Where the link appears (file:line)
• status — Error message (e.g., "404 Not Found", "FileNotFound")
• code — HTTP status code (null for file errors)

---

Step 3: Parse and Filter with jq

Extract all broken links

jq -r '.failures[] | "\(.source): \(.uri)"' link-report.json

Output:

docs/guide.md:42: https://example.com/broken-page
docs/overview.md:15: ./relative/path/file.md

Count broken links by type

jq '.failures | group_by(.status) | map({status: .[0].status, count: length})' link-report.json

Extract only external link failures (HTTP errors)

jq -r '.failures[] | select(.code != null) | "\(.uri) (\(.code))"' link-report.json

Extract only internal link failures (file not found)

jq -r '.failures[] | select(.code == null) | "\(.source): \(.uri)"' link-report.json

Create a fix-ready CSV

jq -r '.failures[] | [.source, .uri, .status] | @csv' link-report.json > broken-links.csv

---

Step 4: Fix Broken Links

Strategy 1: Fix broken internal paths

When a file has been moved or renamed, update all references:

# Before fixing, locate the correct file
find . -name "correct-filename.md" -type f

# Update the link in the source file
# Old: ./relative/path/file.md
# New: ./new/path/correct-filename.md

Use the Edit tool to update each reference:

# Example: fixing a link in docs/guide.md at line 42
# Change: [See the overview](./relative/path/file.md)
# To:     [See the overview](./docs/overview.md)

Strategy 2: Fix broken external URLs

When external links return 404 or timeout:

1. Verify the link is genuinely broken — Use a browser to confirm
2. Find the correct URL — Search the site's current structure
3. Update the reference — Replace with the working URL
4. Add a note — Document why the URL changed (if relevant)

Example flow:

# Broken: https://old-api.example.com/v1/docs
# Fixed:  https://docs.example.com/api/v1

Strategy 3: Add URL exceptions (for flaky external services)

Some external services are flaky or behind auth. Use .lycheeignore:

Create .lycheeignore in the repo root:

# Skip flaky external service
https://flaky-service.example.com/.*

# Skip authenticated endpoints
https://api.github.com/repos/private/.*

# Skip email URLs
mailto:.*

Then re-scan:

lychee <directory>/**/*.md --format json > link-report.json

Strategy 4: Redirect broken links to archived versions

For dead external links with no modern equivalent:

# Old: https://old-docs.example.com/article
# New: https://web.archive.org/web/2023/old-docs.example.com/article

# Update in source file:
# [Old reference](https://web.archive.org/web/2023/old-docs.example.com/article) (archived)

---

Step 5: Verify Fixes

After making corrections, re-scan to confirm:

lychee <directory>/**/*.md --format json > link-report-after.json

Compare the results:

# Before
jq '.stats.errors' link-report.json

# After
jq '.stats.errors' link-report-after.json

# Should be lower or zero

Check specific failures:

jq '.failures | length' link-report-after.json

---

Integration Examples

Shell script for automated link validation

#!/bin/bash
set -e

REPORT_FILE="link-report.json"
FAILED_LINKS_FILE="broken-links.csv"

echo "Scanning for broken links..."
lychee docs/**/*.md --format json > "$REPORT_FILE"

echo "Analyzing results..."
ERRORS=$(jq '.stats.errors' "$REPORT_FILE")

if [ "$ERRORS" -gt 0 ]; then
  echo "Found $ERRORS broken links:"
  jq -r '.failures[] | [.source, .uri, .status] | @csv' "$REPORT_FILE" > "$FAILED_LINKS_FILE"
  cat "$FAILED_LINKS_FILE"
  exit 1
else
  echo "✓ All links valid"
  exit 0
fi

Makefile target for link checking

.PHONY: check-links
check-links:
	@echo "Checking documentation links..."
	@lychee docs/**/*.md --format json | jq -r 'if .stats.errors > 0 then "FAILED: \(.stats.errors) broken links" else "OK" end'

.PHONY: list-broken-links
list-broken-links:
	@lychee docs/**/*.md --format json | jq -r '.failures[] | "\(.source): \(.uri) (\(.status))"'

.PHONY: fix-links
fix-links: check-links
	@echo "Review the list above and update links manually"

GitHub Actions workflow example

name: Link Checker

on: [pull_request, push]

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lycheeverse/lychee-action@v1
        with:
          args: docs/**/*.md --format json
          fail: true
          format: json

---

Structured Data Patterns

When processing lychee output, use jq for reliable JSON parsing:

Get failure count by status code

jq '.failures | group_by(.code) | map({code: .[0].code, count: length})' link-report.json

Extract unique broken URLs

jq -r '.failures[].uri' link-report.json | sort -u

Find all failures in a specific file

jq -r '.failures[] | select(.source | startswith("docs/guide.md")) | .uri' link-report.json

Generate a summary report

jq '{
  total: .stats.total,
  broken: .stats.errors,
  by_type: (.failures | group_by(.status) | map({type: .[0].status, count: length}))
}' link-report.json

---

Guardrails

• Always run a baseline scan first — Understand your starting state before fixing
• Fix internal links before external links — Internal links are easier to validate
• Test external links manually — Not all 404s are permanent; some services may be temporarily down
• Document fixed URLs — If you change a URL, add a comment explaining why (good for future maintainers)
• Use .lycheeignore sparingly — Exclusions should be for genuinely flaky services, not to hide problems
• Re-scan after changes — Always verify that fixes are complete before merging
• Version your reports — Keep baseline and post-fix reports for audit trails

---

Common Issues and Solutions

Issue: Lychee times out on external links

Solution: Increase timeout and reduce concurrent requests:

lychee \
  docs/**/*.md \
  --timeout 60 \
  --max-concurrent-requests 1 \
  --format json > link-report.json

Issue: False positives from dynamic URLs

Solution: Add exceptions in .lycheeignore:

# Dynamic paths that don't resolve without query params
https://example.com/api/.*

Issue: Relative links break after file reorganization

Solution: Update relative paths to be absolute within the repo:

# Before: ../../../other/file.md
# After:  ../../docs/other/file.md
# Or use full path: /docs/other/file.md (if supported by your platform)

Issue: Can't find lychee after devbox install

Solution: Ensure you're running in the devbox shell:

devbox shell
which lychee  # Should show path
lychee --version

---

Advanced: Custom Lychee Configuration

Create a lychee.toml file for reusable settings:

# Timeouts and retries
timeout = 30
max_retries = 3
retry_wait_time = 1

# Exclude patterns
exclude_paths = [
  "node_modules",
  ".git",
  "vendor"
]

# Headers for authenticated requests
headers = [
  "Authorization: token ghp_xxx"
]

# Ignore patterns (similar to .lycheeignore)
ignore_paths = [
  "https://api.github.com/repos/private/.*"
]

Then run with:

lychee --config lychee.toml docs/**/*.md --format json