Links in Markdown: Inline, Reference, Anchor, and More

Links in markdown are fundamental to connecting documents, citing sources, and building navigation in any content you publish. Markdown gives you several distinct link styles, each suited to a different context. This guide covers all of them with clear examples so you can choose the right approach for every situation.

Quick Answer: To add a link in markdown, use [link text](URL) for inline links, [text][label] with a separate [label]: URL definition for reference-style links, and #heading-id for anchor links within the same page. Descriptive link text improves both accessibility for screen reader users and SEO click-through rates by up to 40%.

What Are Inline Links and How Do You Write Them?

The most common way to add a link in markdown is the inline format. You write the visible link text inside square brackets, followed immediately by the URL inside parentheses:

[Visit edtr.md](/app)
[Read the MDN docs](https://developer.mozilla.org)
[Contact us](mailto:hello@example.com)

The parts:

• [link text] - what the reader sees and clicks
• (URL) - the destination, relative or absolute

Adding a title tooltip. You can include an optional title string after the URL (inside the parentheses), wrapped in double quotes. This title appears as a tooltip when the reader hovers over the link:

[edtr.md](/app "Free in-browser markdown editor")

Relative vs. absolute URLs. Use relative paths (/blog/markdown-cheat-sheet) for links within your own site. Use full absolute URLs (https://example.com) for external sites. Relative links are more portable and will not break if your domain changes.

What Are Reference-Style Links and When Should You Use Them?

When your document contains many links, inline URLs can clutter the prose and make the source hard to read. Reference-style links solve this by separating the URL from the text.

You place a label in brackets after the link text:

I use [edtr.md][editor] for all my markdown writing.
The [CommonMark spec][commonmark] defines the standard.

Then, anywhere in the document (typically at the bottom), you define each label:

[editor]: /app "Free in-browser markdown editor"
[commonmark]: https://spec.commonmark.org

The label matching is case-insensitive. [editor], [Editor], and [EDITOR] all refer to the same definition.

Shortcut reference links. When the link text and the label are the same, you can omit the second pair of brackets:

Visit [edtr.md][] for a fast writing experience.

[edtr.md]: /app

Reference-style links are especially valuable in technical documentation, long-form articles, and any document where link URLs are long or frequently reused.

How Do Anchor Links Work in Markdown?

Anchor links let readers jump to a specific section of the same document. Every heading in a markdown document automatically generates an ID based on its text content. To link to a heading, use # followed by the slugified heading text:

## Getting Started

See the [Getting Started](#getting-started) section for details.

Markdown-to-HTML converters generally generate IDs by:

1. Converting the heading text to lowercase
2. Replacing spaces with hyphens
3. Removing any punctuation and special characters

Examples:

Heading	Anchor
## Getting Started	#getting-started
## What Is Markdown?	#what-is-markdown
## Step 1: Install	#step-1-install
## FAQ & Troubleshooting	#faq--troubleshooting

Anchor link behavior can vary between renderers. If you are writing for a specific platform (GitHub, a static site generator, a docs tool), test your anchor links to confirm the ID format it uses. GitHub, for example, lowercases all characters and replaces spaces with hyphens. For a full breakdown of how links, anchors, and references behave specifically on GitHub, see the markdown for GitHub guide.

Linking to a heading in another document:

[See the tables section](/blog/markdown-tables-guide#basic-table-syntax)

What Are Auto-Links in Markdown?

If you want to display a URL as a clickable link without any custom text, wrap it in angle brackets:

<https://edtrmd.com>
<hello@example.com>

Some markdown renderers will also auto-link bare URLs (without angle brackets), but this behavior is not guaranteed across all platforms. Using angle brackets is the safe, explicit approach.

How Do You Link to Images in Markdown?

You can wrap an image in a link so clicking the image navigates to a URL. The image syntax goes inside the square brackets of a link:

[![Alt text for the image](path/to/thumbnail.png)](https://example.com)

This pattern is common for:

• Linked badges (GitHub workflow status, npm version badges)
• Product screenshots that link to demos
• Gallery thumbnails that link to full-size images

For more about image syntax itself, including alt text best practices and sizing, see the guide on images in markdown.

How Do You Open Links in a New Tab in Markdown?

Standard markdown has no syntax for setting a link target attribute. To open a link in a new tab, you need to use inline HTML:

<a href="https://example.com" target="_blank" rel="noopener noreferrer">Open in new tab</a>

The rel="noopener noreferrer" attribute is a security best practice when using target="_blank". It prevents the new page from accessing the opener page via window.opener.

Note that inline HTML works in most markdown renderers, but some platforms strip certain HTML attributes for security reasons. Test your target environment before relying on this approach.

How Do You Disable or Escape Link Syntax in Markdown?

To prevent a URL from being turned into a link, wrap it in a code span:

Do not visit `http://example.com` in production.

To escape the bracket characters so they are not interpreted as a link, use backslashes:

This \[text\] is not a link.

What Makes Good Link Text in Markdown?

Link text quality matters for accessibility, SEO, and readability. Screen readers often present links out of context, reading just the link text to help users navigate. Search engines use link text as a signal for what the destination page is about. According to WebAIM’s accessibility research, 69% of screen reader users navigate a page by jumping between links, making descriptive link text one of the highest-impact accessibility improvements you can make.

Do this:

Read the [markdown syntax guide](/blog/markdown-cheat-sheet) for a quick reference.
Learn more about [anchor links in markdown](#how-do-anchor-links-work-in-markdown).

Avoid this:

Click [here](/blog/markdown-cheat-sheet) for more information.
Learn more [about this](/blog/markdown-cheat-sheet).

Guidelines for link text:

• Describe the destination, not the action (“markdown syntax guide”, not “click here”)
• Keep it concise, two to five words is usually ideal
• Make links distinguishable from each other when they appear in a list
• Never use bare URLs as link text unless the URL itself is meaningful to the reader

What Are the Most Common Link Mistakes in Markdown?

Spaces inside brackets or parentheses. Markdown link syntax is strict about spacing. [ link text ](url) may not render correctly in all parsers. Keep the content tight: [link text](url).

Unescaped parentheses in URLs. If your URL contains a closing parenthesis ), you need to percent-encode it as %29:

[Wikipedia article](https://en.wikipedia.org/wiki/Markdown%29)

Or wrap the URL in angle brackets inside the parentheses:

[Wikipedia article](<https://en.wikipedia.org/wiki/Markdown)>)

Forgetting to define reference labels. If you use a reference-style link but forget to add the label definition, the link will render as raw text [link text][label] rather than an actual link.

Using the same label for different URLs. Reference labels must be unique. If you define the same label twice, the second definition overrides the first.

How Do You Choose the Right Link Style for Your Document?

For a simple document, inline links are the fastest choice. For a long article with many external citations, reference-style links keep the source readable. For navigating between sections of a long page, anchor links are the right tool. And for displayed URLs without custom text, angle-bracket auto-links are explicit and reliable.

Understanding all four styles means you can always choose the one that keeps both your source and your rendered output clean.

Start practicing with links in edtr.md, where live preview shows you immediately whether your link syntax is correct. For a broader reference of markdown syntax elements, see the markdown cheat sheet. If you are writing documentation with many cross-references and anchored sections, the technical documentation with markdown guide covers link strategies for larger projects. If your work involves GitHub specifically, the GitHub Flavored Markdown guide explains the link and reference extensions that GitHub adds on top of CommonMark.