GitHub README Link Checker: How to Find Broken Docs Links
A GitHub README link checker helps you catch broken docs links before a new contributor, customer, or AI assistant follows a dead setup guide. The most useful checks cover external URLs, relative repository paths, table-of-contents anchors, and links that changed after a branch or folder move.
What to Check in a README
- Relative file paths: docs pages, examples, contribution guides, and changelogs.
- Heading anchors: table of contents links and section jumps.
- External references: API docs, package pages, demos, and community links.
- Branch-sensitive links: URLs that still point to an old default branch.
Why README Links Break
README links usually break during ordinary maintenance: files move, docs folders get renamed, headings change, a repository moves from master to main, or an external service removes an old page. The Markdown can still render correctly while the target behind a link is already gone.
A Practical README Link Check Workflow
- Scan the public GitHub README URL or paste the Markdown directly for private repositories.
- Review relative paths and anchors before external URLs.
- Fix internal docs links first because they block onboarding and installation flows.
- Replace expired external docs or community links with stable destinations.
- Export the corrected Markdown and commit it back to the repository.
Best fit
Use a README-specific workflow when you care about GitHub rendering, relative paths, and docs anchors. Use a website crawler only when the README has already been published as a normal web page.
To run the check now, open the GitHub broken link checker or paste the README into the Markdown link checker.
Related 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.
How to Check Markdown Links in Git Repositories Before Release
A straightforward process for reviewing Markdown links in GitHub and GitLab docs before they go live.
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.