Why Markdown Relative Links Break in GitHub and GitLab Docs

Why Markdown relative links break usually comes down to context: the same link can resolve differently depending on the file location, branch, renderer, or export target. That is why README links may look fine during editing but fail after a docs restructure or release.

Common Causes

• Files moved: links like ../setup/install.md no longer point to the same relative path.
• Branches changed: links that work on main may fail in release branches.
• Headings renamed: anchor links break when section titles change.
• Docs exported: static-site generators may rewrite paths differently from GitHub or GitLab.

How to Fix Them

1. Scan the Markdown from the same branch or source context users will read.
2. Fix relative paths after file moves instead of converting every internal doc link to an absolute URL.
3. Check heading anchors after editing section names.
4. Run one final scan after exporting or publishing the docs site.

To check a README or docs file now, use the Markdown link checker or the Git docs link checker for GitHub and GitLab workflows. If you need to repair targets, use the fix Markdown broken links workflow.