When to Use Relative Links vs Absolute Links in GitHub README Files

Use relative links for internal repository content to ensure portability across forks and renames, while reserving absolute links exclusively for external resources.

Choosing between relative links versus absolute links in GitHub README files determines whether your documentation survives repository moves, forks, and renames without breaking. According to the tiimgreen/github-cheat-sheet repository, relative links are the architectural default for internal content because they resolve dynamically against the repository structure. This guide explains the specific implementation rules found in the source code to keep your Markdown maintainable.

Relative Links – The Default for Internal Content

Relative links point to files or headings inside the same repository using paths resolved from the current file's location. The github-cheat-sheet explicitly recommends this approach as the standard for all internal documentation.

As documented in [README.md lines 78-80](https://github.com/tiimgreen/github-cheat-sheet/blob/master/README.md#L78):

"Relative links are recommended in your Markdown files when linking to internal content."

Because GitHub resolves these paths relative to the repository root, they automatically follow the repository if it is renamed, forked, or transferred to a different organization. This eliminates the maintenance burden of updating hardcoded URLs.

Example implementation from the source:

[Link to a header](#awesome-section)
[Link to a file](docs/readme)

Absolute Links – Limited to External Resources

Absolute links contain the full URL (e.g., https://github.com/user/repo/blob/master/...) and should only reference external resources outside the current repository. Using absolute links for internal files couples your documentation to a specific URL structure that breaks when the repository changes location.

The github-cheat-sheet warns in [README.md lines 86-88](https://github.com/tiimgreen/github-cheat-sheet/blob/master/README.md#L86):

"Absolute links have to be updated whenever the URL changes (e.g., repository renamed, username changed, project forked). Using relative links makes your documentation easily stand on its own."

Reserve absolute links for third-party websites, external documentation, or resources hosted in separate repositories where relative paths cannot resolve.

Contribution Guidelines and Enforcement

The repository's contribution standards reinforce this linking policy through explicit requirements. The [CONTRIBUTING.md file at line 13](https://github.com/tiimgreen/github-cheat-sheet/blob/master/CONTRIBUTING.md#L13) states:

"Add a link to your section/category to the contents section (use relative links)."

This mandate ensures that the table of contents and all internal navigation remain functional across every fork and clone of the project.

Link selection criteria:

• Internal files or headings – Use relative links (docs/guide.md, #section). These auto-adjust when the repository moves.
• External sites or other repositories – Use absolute links (https://...). These target fixed external locations.
• GitHub Pages rendering – Prefer relative links to ensure compatibility with Jekyll base URL handling.

Summary

• Relative links (e.g., [Guide](docs/guide.md)) are recommended for all internal content in [README.md lines 78-80](https://github.com/tiimgreen/github-cheat-sheet/blob/master/README.md#L78) because they survive repository renames and forks
• Absolute links require manual updates when repository URLs change and should be limited to external resources only
• The [CONTRIBUTING.md at line 13](https://github.com/tiimgreen/github-cheat-sheet/blob/master/CONTRIBUTING.md#L13) enforces relative links for table of contents entries to maintain portability
• Use [Heading](#heading-id) syntax for same-file anchors and [Label](path/to/file.md) for cross-file references
• Never use absolute URLs for internal files if you want the documentation to function correctly when forked

Frequently Asked Questions

What happens to relative links when a repository is forked?

Relative links continue to function correctly after forking because GitHub resolves them against the new repository's file structure rather than a hardcoded URL. This ensures the documentation remains portable and usable across the entire GitHub ecosystem without requiring any link updates.

Why do absolute links break when a repository is renamed?

Absolute links contain the full URL including the username and repository name (e.g., https://github.com/olduser/oldrepo/blob/master/file.md). When the username or repository name changes, these hardcoded paths become invalid 404 errors, whereas relative links automatically map to the new repository location.

Can I use relative links to reference specific Git commits?

No, relative links cannot point to specific commits because they resolve against the current branch's file tree. To reference a specific commit permanently, you must use an absolute URL including the full commit SHA, such as https://github.com/tiimgreen/github-cheat-sheet/commit/abc123.

How do I create a relative link to a heading in another Markdown file?

Use the file path followed by the anchor hash: [Section Name](docs/other-file.md#section-name). GitHub automatically generates anchors from heading text by converting spaces to hyphens and lowercasing the text, allowing you to link directly to specific sections within the repository structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}