DEV Community

Cover image for How to Catch Broken Markdown Links and Dead Anchors in GitHub Actions Before Deploy
Umut Güngör
Umut Güngör

Posted on Originally published at umutgungorr.com

How to Catch Broken Markdown Links and Dead Anchors in GitHub Actions Before Deploy

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)