Why Markdown links break silently across pull requests
When an engineer renames `docs/setup.md` or edits a heading from `## Authentication` to `## Token Setup`, unit tests and TypeScript builds still pass green. Every code check succeeds while `#authentication` in your README silently becomes a dead jump.
Traditional HTTP crawlers fall short in pull requests for two reasons: they often miss local relative paths and GitHub Flavored Markdown (GFM) heading slugification rules, and external rate limits (429/403) turn deterministic CI runs flaky.
Step 1: Verify relative files, images, and GFM #anchors offline
The cleanest CI gate is deterministic and network-free: validate Markdown links, relative image assets, and exact GFM heading anchors (including Unicode, emojis, punctuation, and duplicate `-1`, `-2` suffixes) directly against the workspace files.
The zero-dependency Python CLI `deadlinkfinder` does more than exit non-zero: when a target breaks, it uses `difflib` similarity matching to print 'did you mean' suggestions for renamed files and headings.
pip install deadlinkfinder
# Repo genelindeki yerel Markdown linkleri, görselleri ve #başlık çapalarını tara
deadlinkfinder check .
# Yalnızca docs klasörünü JSON çıktısıyla ve isteğe bağlı dış URL kontrolüyle tara
deadlinkfinder check docs/ --format json --externalStep 2: Gate pull requests in GitHub Actions with SARIF annotations
Wiring the check into a `pull_request` workflow and passing `--format sarif` output to GitHub Code Scanning surfaces broken links inline on the pull request diff with line-level fingerprints.
Keeping PR checks strictly offline while delegating `--external` URL sweeps to a nightly schedule gives you sub-second deterministic pull request feedback with zero network flakiness.
name: Markdown Link Check
on:
pull_request:
paths:
- "**/*.md"
- "docs/**"
jobs:
links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install deadlinkfinder && deadlinkfinder check .
- name: Generate SARIF report
if: always()
run: deadlinkfinder check . --format sarif > links.sarif
continue-on-error: trueSource: DeadLinkFinder project page and architecture notes
Source: PyPI: deadlinkfinder package
