What is the correct relative link from a docs file to the root README?

If the document is one directory below the root, use ../README.md. Add more ../ segments when the document is deeper.

Should relative paths use backslashes on Windows?

No. Markdown repository paths should use forward slashes, such as docs/setup.md, regardless of the contributor's operating system.

Can I link to a heading in another Markdown file?

Yes. Append the heading fragment to the file path, for example docs/setup.md#requirements, then verify the generated anchor on GitHub.

Why does an image show locally but not on GitHub?

The path may be calculated from the wrong directory, use incorrect capitalization, or point to a file that was not committed. Check the rendered source location and repository tree.

Relative Links in GitHub Markdown

Use a relative Markdown link when the destination lives in the same repository or site structure. Write [setup guide](docs/setup.md) to link from a root README to docs/setup.md. Use ../ to move up one directory, ./ for the current directory, and a filename or folder path to move down. For an image, use ![description](images/logo.png). Relative links usually remain useful across branches, forks, and repository copies because they do not contain a fixed account or repository name. Check the link from the file that contains it. A path that works in the root README may fail from a nested document.

Understand the path from the current file

A relative path starts at the directory containing the Markdown file. In a root README, docs/setup.md points to a file inside the docs directory. In docs/guide.md, setup.md points to docs/setup.md, while ../README.md points back to the repository root. The path is not calculated from the browser address bar or the repository root unless the source file is in that root. Use forward slashes in Markdown paths, including when contributors work on Windows. File and directory names can be case-sensitive after publication, so match the repository spelling exactly. Keep paths simple and avoid unnecessary ./ segments. A directory link may resolve differently depending on the GitHub page and the presence of an index file, so link directly to the intended document when practical.

Link files, headings, and images

Markdown links use a label in square brackets followed by a destination in parentheses. Add a heading fragment after the file path to target a section, such as docs/setup.md#requirements. GitHub generates heading anchors from rendered headings, so test punctuation and duplicate names. Image syntax adds an exclamation mark before the link: ![Architecture diagram](images/architecture.png). The alt text should describe the image's purpose rather than repeat its filename. Put assets in a predictable directory and use a path relative to the Markdown file. Relative links can also point to directories, but a direct file path gives readers a clearer destination. Avoid embedding local computer paths because they do not describe repository content.

Review links before merging

Test relative links from the published GitHub view, not only from an editor preview. Open the source file at its actual repository location, then click each link. Check links after moving a Markdown file, renaming a folder, changing capitalization, or converting a README into a nested guide. A link may work on one branch and fail on another if the target exists only in one branch. Keep changes to paths and file moves in the same pull request when possible. For links that must leave the repository, use a full HTTPS URL and verify that the destination is intentional. Do not use a relative path for an external service or a URL that needs a stable public domain.

How do you do it step by step?

1Find the destination file or image and note its path relative to the Markdown file being edited.
2Move up with ../ or down through folders with a direct path using forward slashes.
3Add the path to Markdown link or image syntax and match filename capitalization exactly.
4Add a heading fragment only after confirming the destination heading and generated anchor.
5Open the rendered GitHub page and test the link from the file's real repository location.

Working example

This repository has a root README, a nested guide, and an image in the assets directory.

Input

From `README.md`:

[Setup guide](docs/setup.md)

![System diagram](assets/system-diagram.png)

From `docs/setup.md`:

[Return to the README](../README.md)

[Requirements](setup.md#requirements)

Result

The root README links down into docs and assets. The nested setup guide uses ../ to reach the root and a same-directory path to reach its Requirements heading.

The heading fragment depends on the rendered heading text. Test it on GitHub after changing the heading.

Frequently asked questions

What is the correct relative link from a docs file to the root README?: If the document is one directory below the root, use ../README.md. Add more ../ segments when the document is deeper.
Should relative paths use backslashes on Windows?: No. Markdown repository paths should use forward slashes, such as docs/setup.md, regardless of the contributor's operating system.
Can I link to a heading in another Markdown file?: Yes. Append the heading fragment to the file path, for example docs/setup.md#requirements, then verify the generated anchor on GitHub.
Why does an image show locally but not on GitHub?: The path may be calculated from the wrong directory, use incorrect capitalization, or point to a file that was not committed. Check the rendered source location and repository tree.