Markdown internal links are a powerful tool to help users navigate your document. These internal links can direct your readers to different sections inside the current page or to a specific part of another Markdown document within the same repository.

Markdown internal links, also known as anchor links, offer a way to link to specific areas within a document. These links come incredibly handy for long documents, providing a seamless navigation experience.

Before diving into how to create internal links, let’s ensure that we understand Markdown’s primary syntax for creating links.

[Link Text](URL)

This Markdown code will render as a clickable hyperlink with “Link Text” being the clickable text, and “URL” being the webpage the user will be directed to when clicking on the link.

To create an internal link in Markdown:

  1. First, you need to create an ID for the section you wish to link. This is done by adding an anchor tag before the header. The ID can be anything you want, but it’s best to keep it related to the section’s title.
<a id="section_id"></a>
### Section Title

We’re using a simple HTML anchor tag (<a>) with an id attribute (?section_id?). The anchor tag is self-closed, meaning it doesn’t need a closing </a> tag.

  1. Now that you’ve assigned an ID to the section, you can create an internal link pointing to it. Use the normal syntax for creating a link in Markdown, but instead of a URL, use the ID prefixed with a #.
[Section Title](#section_id)

When you click on “Section Title,” you will be led to the section with the “section_id.” Here’s an example:

<a id="installation"></a>
## Installation

To install the package do...

[Go to Installation](#installation)

Clicking “Go to Installation” will take the user to the “Installation” section.

Linking to Headers

Markdown automatically turns your headers into anchors, so you can link directly to them without having to create a custom ID. From my earlier Post on How to link to a header in markdown, Markdown converts your headers to anchors using the header’s text, all lowercase, and spaces replaced by hyphens (-).

Example:

### Frequently Asked Questions

[Link to FAQ](#frequently-asked-questions)

Clicking on “Link to FAQ” takes you directly to the “Frequently Asked Questions” header.

However, keep in mind that this feature may not be available in all Markdown renderers. Therefore, using custom IDs is the safer choice, as demonstrated earlier.

Conclusion

Markdown internal links are a vital tool in creating navigable and reader-friendly documentation. Learning how to extend Markdown syntax with a bit of HTML expands the utility and value of your markdown documents, enabling more structured navigation.

In this brief guide, we’ve unpacked how to use anchor links in Markdown to facilitate internal linking within your text, making it dynamically navigable for your readers.