· 7 min read

Relative Links in Markdown

Learn how to use relative links in Markdown for portable, maintainable documentation and websites, especially in GitHub, GitLab, and static site generators.

Learn how to use relative links in Markdown for portable, maintainable documentation and websites, especially in GitHub, GitLab, and static site generators.

Markdown is a lightweight markup language commonly used for formatting text on the web. It is favored for its simplicity and readability, making it an ideal choice for writing documentation, README files, and content for static websites.

One of the essential features of Markdown is its ability to include links, both absolute and relative. In this article, I’ll explain how to use relative links in Markdown, especially in the context of GitHub and GitLab, as well as their application in static site generators.

Relative links are URLs that point to files or resources relative to the current file’s location, rather than using a full path (absolute URL).

These links provide a way to reference other files in the same project or directory structure without specifying the complete path. This makes the links portable, meaning they can adapt if the project’s root directory changes, without needing to update the links.

Example of a relative link:

[Relative Link Example](../images/example.png)

In this example, the ../ notation indicates that the link should go up one directory level from the current file’s location to find the images directory and access the example.png file.

  • Portability - Relative links make it easier to move content within a project or even between projects without breaking links. As long as the relative path remains correct, the links will work regardless of the root directory.

  • Maintenance - They reduce the need for updating links if the project structure changes or if files are moved around within the project. This minimizes maintenance efforts and reduces the risk of broken links.

  • Consistency - When working in a collaborative environment or using version control systems like Git, relative links ensure that everyone accesses the same files, regardless of where the project is cloned or stored.

Basic syntax for relative links in Markdown:

[Link Text](relative/path/to/file)
  • Link Text - This is the clickable text that users will see.
  • Relative Path - The path to the target file relative to the current file’s location.

Examples:

  1. Linking to a file in the same directory:

    [Readme File](README.md)

    This link references another Markdown file named README.md in the same directory.

  2. Linking to a file in a subdirectory:

    [Project Documentation](docs/project-doc.md)

    This link points to the project-doc.md file inside the docs subdirectory.

  3. Linking to a file in a parent directory:

    [License File](../LICENSE)

    This link moves up one directory level to access the LICENSE file.

GitHub supports Markdown rendering across various areas, including README files, wikis, and issues. You can also use inline links in GitHub Flavored Markdown to create hyperlinks within these documents, enhancing navigation and usability.

Using relative links in these contexts allows you to create cohesive and navigable documentation within your GitHub repositories.

Key Points for Using Relative Links in GitHub:

  • Relative links adjust based on the file’s location - If you move a Markdown file within the repository, relative links adjust based on the new location, provided the linked files maintain their relative positions.

  • Links to other Markdown files render correctly - When using relative links to other Markdown files within a repository, GitHub renders these linked files, allowing seamless navigation. For example:

    [Contributing Guidelines](CONTRIBUTING.md)

    Clicking this link in a README.md will navigate to the CONTRIBUTING.md file.

  • Links to images or other assets - You can use relative links to include images and other assets stored in the repository. For example:

    ![Project Logo](assets/logo.png)

    This will display an image named logo.png located in the assets directory.

Example in GitHub README:

# Project Title

Welcome to our project! For more details, refer to the [project documentation](docs/index.md).

![Project Screenshot](images/screenshot.png)

See our [contribution guidelines](CONTRIBUTING.md) for more details.

In this example, clicking the links will take users to the appropriate files relative to the README.md file.

Like GitHub, GitLab also supports Markdown rendering across various sections, including README files, wikis, issues, and merge requests.

Relative links in GitLab behave similarly to those in GitHub, making them ideal for maintaining consistent, navigable documentation.

Example in GitLab README:

# Project Overview

For detailed setup instructions, please refer to the [Setup Guide](docs/setup-guide.md).

![Architecture Diagram](images/architecture.png)

Read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.

Here, the links use relative paths to reference other files within the repository, enhancing the README’s utility.

Static site generators like Jekyll, Hugo, and Gatsby commonly use Markdown to create content.

Relative links are crucial in these environments, as they allow you to build flexible and portable websites.

Advantages in Static Site Generators:

  • Flexibility - When using relative links, the content can easily move between different parts of the site or even different projects without breaking links.

  • Build process compatibility - Static site generators process Markdown files and resolve relative links during the build process. This ensures that the final HTML output maintains accurate links, regardless of the file’s location in the source.

Example in a Jekyll Project:

Suppose you have a Jekyll project with the following structure:

/my-jekyll-site
|-- /_posts
|   |-- 2024-08-30-post-example.md
|-- /assets
|   |-- image.jpg
|-- /docs
|   |-- reference.md
|-- index.md

In the 2024-08-30-post-example.md file, you might write:

---
title: "Post Example"
---

![Sample Image](../assets/image.jpg)

For more information, see the [reference documentation](../docs/reference.md).

These relative links ensure that Jekyll can find the image and the reference documentation based on the file’s location within the project structure.

Linking to a Section Within the Same Markdown File

Relative links can also be used to link to specific sections within the same Markdown file. This is particularly useful for creating a table of contents or navigating to different parts of a lengthy document.

Basic syntax for linking to a section:

[Link Text](#section-heading)
  • Link Text: The clickable text that users will see.
  • #section-heading: The section you want to link to, using the heading text formatted in lowercase and with spaces replaced by hyphens.

Example:

Suppose you have the following headings in your Markdown file:

## Introduction

## Features

## Installation

To link to the “Installation” section from anywhere in the same file, you would use:

[Go to Installation](#installation)

This link will navigate directly to the “Installation” section when clicked, allowing users to quickly jump to different parts of the document.

Handling Special Characters in Headings:

When linking to headings that contain special characters, such as punctuation or symbols, you need to format the link appropriately:

  • Remove or replace special characters: Most special characters (e.g., !, ?, @, etc.) should be removed or replaced with hyphens.
  • Spaces become hyphens: Replace spaces with hyphens (-).

For instance, if you have a heading like this:

## What's New?

The link should be formatted as:

[Go to What's New](#whats-new)

Note: The question mark and apostrophe are removed, and spaces are replaced with hyphens.

Caution with Auto-Generated IDs by Static Site Generators:

When using static site generators (e.g., Jekyll, Hugo, Gatsby), be aware that they might auto-generate IDs for headings based on their own rules. These IDs could differ from the ones you manually specify. To ensure your links work as expected:

  • Verify IDs: Check the generated HTML output to verify the exact IDs used by the site generator.
  • Consistent Heading Formats: Use consistent and predictable heading formats to reduce discrepancies.
  • Custom ID Assignment: Some generators allow you to assign custom IDs to headings, ensuring that your links match the specified IDs. For example:
## Introduction {#introduction}

[Go to Introduction](#introduction)

Using these practices will help maintain accurate internal linking, improving navigation and user experience in your Markdown files.

Conclusion

Relative links in Markdown provide a powerful way to reference other files, images, and resources within a project, making documentation more manageable and portable. They are especially valuable in version-controlled environments like GitHub and GitLab, where maintaining accurate and navigable documentation is critical.

When used with static site generators, relative links contribute to a seamless content creation process, ensuring that links remain intact regardless of project structure changes.

By understanding how to use relative links effectively, you can create more robust, scalable, and maintainable documentation and websites that adapt easily to changes and are user-friendly for your collaborators and readers.

    Share:
    Back to Blog