Markdown Links: Inline, Reference, and Auto-Links

Links are one of the most-used features in markdown. The basic syntax is [text](url), but there are several variations depending on how you want to organize your document and what platform you’re writing for.

This guide covers every link type, from the basics through reference-style links, anchor links, and auto-links, with platform-specific notes and copy-paste templates.

Basic Syntax

An inline link wraps the visible text in square brackets and the URL in parentheses:

[MDtoLink](https://mdtolink.com)

You can add an optional title that appears on hover:

[MDtoLink](https://mdtolink.com "Publish markdown to shareable URLs")

The title goes inside double quotes after the URL, separated by a space. Most browsers show this as a tooltip when the user hovers over the link.

Reference-Style Links

When a paragraph has many URLs, inline links make the source hard to read. Reference-style links solve this by moving the URL to a separate line:

Read the [getting started guide][1] or check the [API docs][api].

[1]: https://mdtolink.com/docs/getting-started
[api]: https://mdtolink.com/docs/api "API documentation"

The reference label (the part in the second set of brackets) can be a number or a word. The definition line can go anywhere in the document. The renderer collects and resolves them all.

You can also use an implicit label where the link text itself is the reference:

Check the [API docs].

[API docs]: https://mdtolink.com/docs/api

Reference links are a good fit for README files, long-form documentation, and academic writing where readability of the source matters.

Auto-Links

Wrapping a URL in angle brackets makes it clickable without separate link text:

<https://mdtolink.com>
<user@example.com>

GitHub Flavored Markdown (GFM) goes further and auto-links bare URLs without angle brackets:

Visit https://mdtolink.com for more.

Standard CommonMark does not auto-link bare URLs. If you need your document to work across all parsers, use the angle bracket syntax or a full inline link.

Anchor Links (Same-Page Links)

Anchor links point to a heading on the same page. Most markdown renderers generate an ID from each heading by lowercasing the text and replacing spaces with hyphens:

## My Section Title

...

Jump to [My Section Title](#my-section-title).

Rules for generating heading IDs vary by platform:

If your heading is ## What's New in 2026?, the generated ID on GitHub would be #whats-new-in-2026. The question mark and apostrophe are stripped.

For headings with duplicate text, GitHub appends -1, -2, etc. to keep IDs unique.

Email Links

Use angle brackets around an email address to create a mailto link:

<hello@example.com>

This renders as a clickable email link. Some renderers encode the address to reduce spam harvesting, but this is not guaranteed.

You can also use a full inline link with a mailto: prefix:

[Email us](mailto:hello@example.com)

Links Inside Other Elements

Links work inside most markdown elements, but there are a few edge cases.

Bold or italic link text:

[**Bold link**](https://example.com)
[*Italic link*](https://example.com)

Link inside a list:

- [First item](https://example.com)
- [Second item](https://example.com)

Link inside a table cell:

| Name | Link |
|------|------|
| Docs | [Read here](https://example.com) |

Link inside a blockquote:

> Read the [full guide](https://example.com) for details.

Image as a link (wrap the image syntax in link brackets):

[![Alt text](image.png)](https://example.com)

Opening Links in a New Tab

Standard markdown has no syntax for target="_blank". If you need a link to open in a new tab, fall back to HTML:

<a href="https://example.com" target="_blank" rel="noopener noreferrer">Example</a>

The rel="noopener noreferrer" attribute is a security best practice when using target="_blank".

Some markdown processors support extended syntax or plugins for this, but it is not part of CommonMark or GFM.

Platform Differences

Common Mistakes

Forgetting the protocol. [Link](example.com) creates a relative link, not an absolute one. Always include https://:

<!-- Wrong -->
[Link](example.com)

<!-- Correct -->
[Link](https://example.com)

Spaces between brackets and parentheses. Some parsers fail if there is a space between ] and (:

<!-- Might break -->
[Link] (https://example.com)

<!-- Always works -->
[Link](https://example.com)

Unescaped parentheses in URLs. If your URL contains parentheses (common in Wikipedia links), encode them or use angle brackets:

<!-- Breaks -->
[Article](https://en.wikipedia.org/wiki/Markdown_(software))

<!-- Fix with encoding -->
[Article](https://en.wikipedia.org/wiki/Markdown_%28software%29)

<!-- Fix with angle brackets (reference style) -->
[Article]: <https://en.wikipedia.org/wiki/Markdown_(software)>

Copy-Paste Templates

Basic link:

[Link text](https://example.com)

Link with title:

[Link text](https://example.com "Title text")

Reference link:

[Link text][ref]

[ref]: https://example.com "Optional title"

Anchor link:

[Jump to section](#section-heading)

Email link:

<hello@example.com>

Image as a link:

[![Alt text](image.png)](https://example.com)

FAQ

How do I create a markdown link?

Use square brackets for the text and parentheses for the URL: [text](url). For example, [Google](https://google.com) creates a clickable link that displays “Google” and points to google.com.

How do I link to another section on the same page?

Use an anchor link with # followed by the heading text in lowercase with hyphens instead of spaces: [Go to FAQ](#faq). The heading ID is auto-generated by most renderers.

What is the difference between inline and reference-style links?

Inline links put the URL right after the text: [text](url). Reference links separate the URL into a definition elsewhere in the document: [text][label] with [label]: url on its own line. Both render identically. Reference links keep long documents more readable.

Can I open a markdown link in a new tab?

Markdown has no built-in syntax for this. Use an HTML anchor tag: <a href="url" target="_blank" rel="noopener noreferrer">text</a>. Some markdown processors strip this HTML for security reasons.

Try It Out

Write your links and see them render in real time with the MDtoLink editor. When you’re ready, publish your document to a shareable URL with one click.

For a quick syntax refresher, check the markdown cheat sheet. Want to add images alongside your links? See the markdown images guide.