In Markdown, links are a key tool for facilitating navigation, providing references, and enriching the reader’s experience.
Links can be:
- Internal, directing to other sections within the same document (or the same website)
- External, taking the reader to external websites or resources
External Links
External links allow readers to access resources outside the document, such as relevant websites, articles, or databases.
To create an external link in Markdown, use the following syntax:
[Link Text](URL-of-the-link)
For example, this Markdown snippet:
[www.luisllamas.es](https://www.luisllamas.es)
Renders as:
Links with Text and Description
Sometimes, it’s useful to provide an additional description of the link. You can do this by adding an optional title in quotes after the URL.
[www.luisllamas.es](https://www.luisllamas.es "Complete Markdown Guide")
This renders as:
When the reader hovers over the link, they will see the descriptive text provided.
Internal Links
Internal links are useful for navigating between different sections within the same document.
Markdown does not natively support internal links in all engines, but it’s possible in many environments, especially on platforms like GitHub and GitLab.
To create an internal link, use the following syntax:
[Link Text](URL-of-the-link/#anchor-name)
Where #anchor-name corresponds to the identifier of the section you want to link to. This identifier is based on the text of the heading you are linking to, converted to lowercase and with spaces replaced by hyphens.
For example:
[Internal Links](/how-to-use-links-in-markdown/#internal-links)
This renders as:
If you click on it, it will take you to this same page, to the beginning of the “Internal links” section.
Finally, we can also underline or highlight a piece of text. For that, we must indicate the beginning and end of the text we want to highlight, for example like this:
[Highlighted Internal Link](/#internal-links:~:text=Internal%20links,Github%20and%20Gitlab)
Which renders as:
If you click it, it will take you to the beginning of the “Internal links” section, with the first paragraph selected.
Best Practices Tips
Clarity in Link Text: Use clear and descriptive text so the reader understands the purpose of the link before clicking.
Personally, I don’t use the floating tooltip part because it causes issues on some platforms. But the text, yes.
External Links: External links can break because they don’t depend on you. Make sure external links are relevant and provide additional value to the content. If not, don’t add them.
