How to Check Markdown Links in Git Repositories Before Release
Documentation quality influences adoption. A fast markdown dead link checker workflow helps prevent broken onboarding paths, failed setup steps, and support tickets caused by stale README links.
Where Markdown Links Fail Most Often
Most failures come from renamed folders, moved docs, branch changes, and invalid heading anchors.
Technical Note: Raw Content Links
Never link to the raw file URL (e.g., raw.githubusercontent.com/...) if you want to display the file in the GitHub UI. Always use the blob URL or, better yet, a relative path.
Fast Validation Flow
Instead of manual checking, scan the README URL with DeadLinkTool. Our engine automatically:
- Fetches the Markdown source code.
- Identifies all
[text](url)patterns. - Resolves relative paths based on your repo structure.
- Executes parallel HEAD requests to verify link health.
CI/CD Enforcement
To prevent documentation decay, integrate a link checker into your GitHub Actions. This ensures that no Pull Request is merged if it introduces a broken link.
name: Documentation Check
on: [pull_request]
jobs:
link-checker:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check Links
uses: lycheeverse/lychee-action@v1.9.0
with:
args: --verbose --no-progress README.mdRelated workflows
Use the workflow page that matches your source format so the checker and fixing options stay accurate.
Ready to clean your links?
Open the workflow that best matches this guide and check your links in seconds.
Open Markdown link checkerRelated Guides
5 README Link Mistakes That Break Docs on GitHub
The most common Markdown link mistakes in GitHub READMEs, and how to catch them before they confuse new users.
GitHub README Link Checker: How to Find Broken Docs Links
Use a GitHub README link checker to validate README links, relative paths, anchors, and external references before users hit dead docs.
Why Markdown Relative Links Break in GitHub and GitLab Docs
Understand why Markdown relative links break after file moves, branch changes, renamed anchors, and documentation exports.