Markdown Links Explained: How to Add Links in Markdown

Links are the connective tissue of the web, and knowing how to add links in Markdown is one of the first skills you'll want to master. Markdown links come in several flavors — inline, reference, and auto-link — and each has a syntax designed to stay readable even in plain text. Whether you're writing a README, a blog post, or product docs, this guide walks through every common way to create markdown links, with copy-paste examples you can drop straight into our online Markdown viewer. If you're brand new to the format, pair this with our primer on what Markdown is.

Markdown Links at a Glance

Before we get into the details, here's a quick comparison of the main link styles you'll encounter:

Link type	Syntax	Best for
Inline link	[text](url)	Everyday links in paragraphs and lists
Inline link with title	[text](url "title")	Adding a tooltip on hover
Reference link	[text][id] + [id]: url	Reusing the same URL many times
Auto-link	<url>	Turning a raw URL into a clickable link
Bare URL	https://example.com	Casual chat; not supported everywhere

You can try any of these live in the homepage editor — paste the syntax and watch it render instantly in your browser, with nothing sent to a server.

How to Add Links in Markdown: Inline Links

The inline link is the workhorse of markdown links. The syntax wraps the clickable text in square brackets, immediately followed by the destination URL in parentheses:

Here is a link to the [Markdown cheat sheet](/blog/markdown-cheat-sheet).

Renders as: Here is a link to the Markdown cheat sheet (linked to that path).

A few practical notes:

• No space between the closing ] and the opening (. A stray space breaks the link.
• The link text can be a single word, a phrase, or even span code, like [`code`](url).
• URLs can be relative (as above) or absolute, like https://example.com/page.
• You can link images by wrapping an image in the link syntax: [![alt](image-url)](link-url).

Visit [MD File Viewer](https://mdfileviewer.com) to preview your files instantly.

Adding Link Titles for Tooltips

Markdown lets you attach a human-friendly title to any inline link. Browsers show it as a tooltip when a reader hovers, and some screen readers announce it. Just add the title inside the parentheses, in quotes, after the URL:

Read the [GFM spec](https://github.github.com/gfm/ "GitHub Flavored Markdown Spec") for the full rules.

The title is optional and decorative — leave it out if it doesn't add value. Note that reference-style links can also carry a title; we'll cover that next. For more GFM-specific syntax, see our GitHub Flavored Markdown guide.

Reference-Style Links

When the same URL appears several times — or when your paragraph is getting cluttered with long URLs — reference links keep your prose clean. You write a short reference where the link goes, then define the destination elsewhere in the document.

Check out the [viewer][1] and the [cheat sheet][1] — both live on the site.

[1]: /md-viewer "Free Markdown viewer"

Two parts:

1. The reference itself, written as [text][id], where id is a label you choose (letters, numbers, or words).
2. The definition, written as [id]: url "optional title", usually grouped at the bottom of the file or section.

A couple of conveniences:

• The label is case-insensitive and can contain spaces, so [my guide] and [MY GUIDE] match the same definition.
• You can use an implicit form: [text][] followed by [text]: url, where the text itself is the label.
• Definitions are not rendered as visible content; they're resolved into links.

This is the [MD File Viewer][] — fast and private.

[md file viewer]: /md-viewer

Reference links shine in longer documents. For most README sections, though, plain inline links are clearer; our Markdown for README guide has more on structuring those files.

Auto-Links and Bare URLs

Sometimes you want the URL itself to be the clickable text. Markdown gives you two ways to do that.

Angle-bracket auto-links turn a raw URL or email address into a link automatically:

Sign up at <https://example.com> or email <[email protected]>.

GFM extends this: bare URLs and email addresses (no angle brackets) also become clickable links in many renderers.

Visit https://example.com today.

Be aware that bare-URL auto-linking is a GitHub Flavored Markdown feature and is not part of the original Markdown spec, so some older or stricter renderers will leave them as plain text. When in doubt, wrap the URL in angle brackets. You can confirm how your renderer behaves by pasting a sample into the online viewer.

Linking to Headings and Anchors

Long documents benefit from in-page navigation. In most Markdown renderers (including GFM), every heading gets an automatic anchor derived from its text: lowercase, spaces replaced with hyphens, and most punctuation stripped.

## Section Two

Jump back to [Section Two](#section-two).

A few rules of thumb:

• The anchor is based on the heading text as written, with spaces → -.
• Duplicate headings get -1, -2, and so on appended.
• Anchors are case-insensitive but the punctuation handling varies by renderer — test before relying on it.

This is especially handy in long READMEs and documentation tables of contents.

Common Mistakes to Avoid

Most broken markdown links come down to a handful of small errors. Here are the ones to watch for.

A space between ] and (. It silently disables the link:

[broken] (https://example.com)   <!-- renders as plain text -->
[works](https://example.com)     <!-- correct -->

Unclosed parentheses in the URL. If the destination URL itself contains ) — common in Wikipedia links — the parser may cut the link short. Wrap the URL in angle brackets to fix it:

[Article](https://en.wikipedia.org/wiki/Example_(disambiguation))   <!-- risky -->
[Article](<https://en.wikipedia.org/wiki/Example_(disambiguation)>) <!-- safe -->

Spaces in the URL. Real URLs can't contain spaces. If you need one, encode it as %20, or — better — avoid spaces in links entirely.

[broken](https://example.com/my file.pdf)
[fixed](https://example.com/my%20file.pdf)

Forgetting the reference definition. A [text][id] with no matching [id]: url renders as broken text rather than a link. Always define every reference label you use.

Mismatched brackets in nested formatting. Combining links with bold or italic inside the link text is fine, but keep the brackets balanced:

**[Bold link](url)**          <!-- correct -->
[**Bold link**](url)          <!-- also correct -->

Frequently Asked Questions

How do I open a link in a new tab in Markdown?

Standard Markdown has no built-in syntax for target="_blank". To open links in a new tab you need raw HTML:

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

Many Markdown renderers pass through inline HTML like this; check your renderer's docs to be sure.

Can I link an image in Markdown?

Yes. Wrap an image element in a link element. The image becomes the clickable text:

[![Logo](logo.png)](https://example.com)

What's the difference between inline and reference links?

Inline links put the URL right next to the text — easiest to read and write for short documents. Reference links move the URLs to a separate list, keeping prose tidy in longer writing. They render identically; it's purely an authoring choice.

Do markdown links work in email?

If your Markdown is converted to HTML before sending, links work exactly like normal web links. If the email client renders Markdown directly (some do), inline and auto-links are the safest choices, since reference-style support varies.

Wrapping Up

That covers every common way to create markdown links: inline links with optional titles, reference links for repeated URLs, auto-links and bare URLs, and in-page heading anchors — plus the handful of mistakes that break them. Master these and you can connect any two pieces of content cleanly, whether you're writing a README, a wiki, or a blog post. Paste your next draft into the homepage editor to preview your links live, and keep our Markdown cheat sheet bookmarked for quick reference.