Markdown Links Syntax - Tutorial

Markdown links are the magic that weaves words into hypertext tapestries. Whether you’re crafting a blog post, a README file, or simply want to share interesting resources, mastering Markdown hyperlinks unlocks a world of interactive possibilities. Let’s dive into the code and explore how to use them effectively.

The Basics of Markdown Links

The syntax for creating a basic Markdown link is simple. It consists of two parts:

1. The link text is enclosed in square brackets []. This is the visible text that the reader will click on.
2. The target URL is enclosed in parentheses (). This is where the link will point when clicked.

Put together, it looks like this:

[link text](URL)

For example:

[Markdown](https://daringfireball.net/projects/markdown/)

The rendered output:

Markdown

When creating links, make sure to use descriptive link text that gives the reader a sense of what the link destination is about. For example, “how to contribute to our docs” is better than just “click here”.

Always test your links after creating them to make sure they point to the correct destination. A broken link provides a poor user experience.

Internal Links: Navigating Your Own Pages

If you’re working with multiple Markdown files, internal links become your best friends. These links connect different sections within your project, creating a seamless reading experience.

The key here is using relative paths. Instead of the full URL, include only the path to the target file, starting with a forward slash /. For instance:

Read more about [formatting](/formatting-guide.md).

This assumes you have a separate formatting-guide.md file in the same directory. Clicking the link takes the reader directly there.

Bonus Tip: Don’t forget the leading slash in internal link paths! It acts as a roadmap, telling Markdown where to find the linked file.

Linking to Headings: Anchoring Your Content

Want to jump straight to a specific section within a page? Internal links can handle that too! Page headings often have unique IDs, acting as anchors. You can find these IDs by hovering over a heading and copying the link from your browser’s address bar.

Here’s how to use the ID to create a Markdown link to section:

Jump to the [conclusion](#conclusion).

Replace #conclusion with the actual ID of the heading you want to link to. This allows readers to navigate directly to the relevant section, enhancing their reading experience.

The rendered output:

Jump to the conclusion.

This example links to an anchor on another page:

Jump to the [conclusion](/page/#conclusion).

External Links: Reaching Beyond Your Pages

The internet is a vast sea of information, and Markdown links allow you to connect your content to the wider world. Simply use the full URL of the external website you want to link to:

Explore the wonders of the [Natural History Museum](https://www.nhm.ac.uk/).

The rendered output:

Explore the wonders of the Natural History Museum.

This creates a clickable link that opens the museum’s website in a new tab or window. Remember, external links should be relevant and add value to your content.

Link Titles: Accessibility Matters

Ever wondered what the little text that pops up when you hover over a link is called? That’s a link title, and it’s not just for decoration. Link titles are crucial for accessibility, especially for users with screen readers.

Adding a link title is simple: just enclose your desired text in parentheses "" after the URL:

Visit [Wikipedia](https://en.wikipedia.org/ "The world's largest online encyclopedia").

The rendered output:

Visit Wikipedia.

This ensures everyone, regardless of their browsing method, understands where the link leads, making your content inclusive and user-friendly.

Autolinking URLs and Email Addresses

Markdown makes it easy to quickly link to URLs and email addresses by autolinking them when surrounded by angle brackets <>.

For example:

<https://htmlmarkdown.com/>

The rendered output: https://htmlmarkdown.com/

And for email:

<mailto:test@example.com>

The rendered output: mailto:test@example.com

Autolinking creates clickable links for URLs and mailto links for emails automatically. However, use standard Markdown links for readability when possible.

Images with Links: The Visual Connection

Images can be powerful storytelling tools, and linking them to relevant websites adds another layer of interactivity. Here’s a Markdown image link:

![Alt text](https://image.example.com "Link title") linked to [Website name](https://website.com).

Replace the placeholders with your image details and website information. This creates an image that, when clicked, opens the linked website in a new tab.

Remember: Accessibility is key! Provide clear alt text for the image itself, and ensure the linked website aligns with your content’s purpose.

Markdown Links: My Personal Experience

As a technical writer who uses Markdown almost daily, links have become an indispensable part of my workflow. They allow me to enrich my content by connecting my readers to valuable resources both within my documentation and across the web.

Linking to Related Content

One of my most common uses for Markdown linking is to connect related content together within my documentation sites. For example, if I mention a concept like “variables” on one page, I can link to my in-depth variables documentation page to allow readers to easily learn more.

I also reciprocally link pages together that cover complementary topics. This gives readers natural pathways to navigate my docs and go deeper on concepts that interest them.

Using descriptive link text helps cue readers on where my internal links will take them. I avoid generic phrases like “click here” in favor of contextually relevant terms pulled from the page I’m linking to.

Linking to External Resources

In addition to internal linking between my own pages, I also liberally link out to high quality external resources. This allows me to succinctly explain a concept on my own page and point readers to more in-depth sources for further reading.

I’m careful to vet any sites I link to from my documentation to ensure they are authoritative and up-to-date. My readers trust me to provide useful external resources, so I want to curate these recommendations.

When linking externally, I still use descriptive link text and provide context around where the link goes and what readers will find there. This smooths the journey for curious readers venturing outside my docs.

Using Absolute Paths

One technical challenge I ran into frequently was getting my internal links routes correctly. At first, I used relative linking paths, but these often broke when my site structure changed or content got moved around during reorganization.

Now I use “absolute” linking paths that start from the root folder of my site. For example, [/content/pages/my-page] instead of [../pages/my-page] from the current page location.

While more verbose, absolute linking has made my life easier by creating resilient links that rarely break. I’d recommend this approach for any large or complex Markdown project.

➽ Checkout my article about Markdown tables.

Mastering Markdown Links: A Final Note

Markdown links are versatile tools that empower you to weave connections within and beyond your content. From simple navigation to enriching your content with relevant resources, remember these key points:

• Use clear and concise link text.
• Prioritize accessibility with link titles.
• Choose internal or external links strategically.
• Leverage autolinking cautiously.
• Don’t forget the power of images with links.

By following these guidelines and exploring the various.