Skip to content
markdown→html

Syntax Reference

Markdown Links

Markdown links use the form [text](url) — square brackets for the visible text, parentheses for the destination. The syntax supports optional title tooltips, reference-style definitions, same-page heading anchors, and automatic linking of bare URLs.

Key facts

Inline form
[text](url)
Reference form
[text][label] + [label]: url
Title syntax
(url "Title")
Autolinks
<url> (CommonMark); bare URLs (GFM)

How do you write a link in Markdown?

Write the visible text in square brackets, immediately followed by the URL in parentheses: [text](url). No space is allowed between the closing bracket and the opening parenthesis. The link converts to an <a> element.

The URL can be absolute (https://example.com/page) or relative (/page). To see the conversion live, paste a link into Markdown Links & Images to HTML.

markdown
[Markdown Guide](https://example.com/guide)
html
<a href="https://example.com/guide">Markdown Guide</a>

How do you add a title to a link?

Add a quoted title after the URL, separated by a space: [text](url "Title"). The title becomes the HTML title attribute and appears as a tooltip when readers hover over the link.

markdown
[spec](https://commonmark.org "CommonMark specification")
html
<a href="https://commonmark.org" title="CommonMark specification">spec</a>

What are reference-style links?

Reference-style links split the link into a usage and a definition. Write [text][label] in the prose and [label]: url on its own line anywhere in the document. Both forms produce identical HTML.

Reference style keeps paragraphs readable when URLs are long. Labels are case-insensitive, and one definition can serve many usages. Most writers collect definitions at the end of the file.

markdown
Read [the spec][cm].

[cm]: https://commonmark.org
html
<p>Read <a href="https://commonmark.org">the spec</a>.</p>

How do you link to a heading on the same page?

Link to the heading's generated anchor: [text](#heading-anchor). Anchors derive from the heading text — lowercased, spaces replaced with hyphens, punctuation removed. ## Getting Started becomes #getting-started.

This slug algorithm is GitHub's convention and is shared by most renderers. Verify anchors on long documents — duplicate headings get -1, -2 suffixes.

markdown
[Jump to setup](#getting-started)
html
<a href="#getting-started">Jump to setup</a>

What are autolinks?

Autolinks turn a URL into a link without bracket syntax. CommonMark requires angle brackets: <https://example.com>. GitHub Flavored Markdown also links bare URLs automatically. Both emit a normal <a> element.

Email addresses autolink the same way: <hello@example.com> emits a mailto: link. See GitHub Flavored Markdown for the other GFM extensions.

markdown
<https://example.com>
html
<a href="https://example.com">https://example.com</a>

Frequently Asked Questions

Can Markdown links be relative?
Yes. [text](/docs/setup) and [text](../readme.md) are valid. The browser resolves the path against the URL of the page hosting the converted HTML, not your Markdown file's location.
How do I escape square brackets in link text?
Prefix the bracket with a backslash: \[. Escaping stops the bracket from starting link syntax, so the character renders literally in the output text.
How do I make an email link?
Wrap the address in angle brackets: <hello@example.com>. Converters emit <a href="mailto:hello@example.com">. The explicit form [Email us](mailto:hello@example.com) works everywhere too.
Why is my link not rendering?
The most common cause is a space between ] and (: writing [text] (url) breaks the syntax. Unbalanced brackets and missing parentheses are next. Remove the space and the link converts.