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 # Scan workspace Markdown links, images, and #heading anchors offline deadlinkfinder check . # Scan docs/ with JSON output and optional external URL check deadlinkfinder check docs/ --format json --external 

Step 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: true 

Originally published at umutgungorr.com/blog/github-actions-broken-links-deadlinkfinder.
Source & architecture notes: DeadLinkFinder case study · GitHub · PyPI