GitHub is a powerful platform for hosting and collaborating on code repositories, and Markdown files are commonly used for documentation. Using relative links in your Markdown files can help keep your documentation organized and easy to navigate, regardless of the branch or directory structure. This article will guide you through using relative links effectively in your GitHub Markdown files.

What Are Relative Links?

Relative links are hyperlinks that point to another file or location within the same repository. Unlike absolute links, which use the full URL, relative links are based on the current location of the file. This makes them more flexible and portable, especially when working with different branches or cloning repositories.

Example:

- Absolute Link -
C:/main_folder/project_1/docs/readME.md

- Relative Link -
docs/readME.md

Why Use Relative Links?

• Portability: Since relative links don’t rely on the full URL, they remain valid regardless of where the repository is hosted.
• Branch Independence: Relative links work seamlessly across different branches, making it easier to maintain consistent documentation.
• Ease of Maintenance: Updating file structures or moving files doesn’t break relative links as long as the relative paths remain the same.

GitHub Relative Links in the Markdown File:

GitHub uses a Markdown file to maintain documentation (i.e, README.md) for every repository. To represent a link of another file, image from the same repository or from external resource, it uses a standard markdown format given below.

[Text-to-display](relative_link)

Possible Approaches:

In two ways, GitHub relative links can be used in markdown files.

• File within same folder or sub folder

Linking achievements.md file to academics.md file

• File present in upward folders

Linking all the files present in pages folder to readme.md file

How to get relative links?

If you use VSCode editor, then right click the file and click copy relative path.

VSCODE

Or right click the file and copy the file path. This method will give the absolute path of a file, edit the absolute link to get relative link

For example: The absolute link is E:/username/project-folder/sub-folder/file.md and the relative link would be sub-folder/file.md

How to get relative links in GitHub ?

Go to the file’s location on the GitHub and copy the link. Refer the below image.

GitHub

And edit it according to where you want to place the link.

How to implement?

File within same folder

This approach is used to link the files that are present in the same folder or its sub folder. In the given image, adding the relative link of the achievement.md to the academics.md file. This can be implemented by the following:

- Achievements.md -

- Won First Hackathon // Content present in achievements.md

- Academics.md -

- Currently a student at SRM
[Achievements](achievements.md)  // File in the same folder

File in Sub folder

Let’s say for example, the achievements.md file present inside a achievement directory and both achievement folder and academics.md file present in a same folder named Education, it can implemented as below.

- Academics.md -

- Currently a student at SRM
[Achievements](achievement/achievements.md) // File in the sub-folder

Output Preview of Academics:

Currently a student at SRM
Won First Hackathon

Linking file in the Upward folder

This approach is used to link the files that are present in the other folder which is not a sub folder. For example, in the given image we are trying to link the files (achievements.md, academics.md, etc) from the pages folder to the README.md markdown file present in the static folder which is outside the pages folder, it can be implemented as below.

- README.md -

[Achievement](../pages/achievements.md)
[Academics](../pages/academics.md)

To link the files present in parent folder or in other folder which is not a sub folder, we can use more ‘ ../ ‘ operator. For example, we want to link the file present in the project folder (parent folder) from pages folder, we can use the below format.

- Project.md -

[Project Readme File](../../README.md)

Output preview of README.md and Project.md

Won First Hackathon
Currently a student at SRM

Important Notes:

This relative link feature is not only to specify the markdown file as a target element, but it also used to specify other file formats such as image, text file, pdf, etc.