Markdown links: inline, reference, relative, and autolinks

To add a link in Markdown, put the clickable text in square brackets followed immediately by the URL in parentheses, like [text](https://example.com). This is an inline link, and the closing bracket and opening parenthesis must touch with no space between them. You can add an optional title in quotes after the URL. Markdown also supports reference-style links, which put the URL in a separate definition, and autolinks, which wrap a bare URL in angle brackets.

Markdown links syntax reference

Markdown links key facts

• The inline link syntax is square-bracketed text followed by the URL in parentheses, such as [text](https://example.com), with no space between the two.
• Every link form compiles to the HTML <a> anchor element with an href attribute.
• An optional title in quotes after the URL becomes the anchor's title attribute, usually shown as a tooltip.
• Reference-style links put the URL in a separate definition, such as [text][id] with [id]: https://example.com, which keeps prose readable.
• Autolinks wrap a bare URL or email in angle brackets, such as <https://example.com>, and are defined by CommonMark.
• A root-relative URL that starts with a slash resolves from the site root, while a relative URL without a slash resolves from the current page.

Choose the link form for maintenance and portability

Use an inline link when the destination appears once and keeping it beside the text aids editing. Use a reference-style link when a long URL repeats or would interrupt a paragraph. Use a relative link for files and pages that move together inside the same repository.

Descriptive link text should explain the destination without relying on “click here.” Encode or wrap destinations containing spaces and parentheses carefully, then test them in the target renderer. For visible URLs and email addresses, see Markdown autolinks. For an image that acts as a link, see Markdown images.

Basic syntax

To create an inline link, put the link text in square brackets, then the URL in parentheses immediately after, with no space between the two.

Markdown

Read the [Markdific docs](https://markdific.com) to get started.

Rendered output

HTML output

<p>Read the <a href="https://markdific.com">Markdific docs</a> to get started.</p>

The text inside the square brackets can contain other inline formatting, such as bold or code. The URL in parentheses should not contain unescaped spaces; wrap it in angle brackets if it does, like [text](<https://example.com/a b>).

Links with a title

Add a title by placing a quoted string after the URL, separated by a space. The title becomes the link's title attribute in HTML, which most browsers show as a tooltip on hover.

Markdown

Visit the [editor](https://markdific.com/markdown-editor-online "Try Markdific online").

Rendered output

HTML output

<p>Visit the <a href="https://markdific.com/markdown-editor-online" title="Try Markdific online">editor</a>.</p>

Titles can be wrapped in double quotes, single quotes, or parentheses. Double quotes are the most common and the most portable choice.

Reference-style links

Reference-style links separate the link text from the URL. You mark the text with a label, then define the URL for that label elsewhere in the document, usually at the bottom. This keeps prose readable when URLs are long.

Markdown

See the [official spec][cm] and the [GitHub spec][gfm] for details.

[cm]: https://spec.commonmark.org
[gfm]: https://github.github.com/gfm/

Rendered output

HTML output

<p>See the <a href="https://spec.commonmark.org">official spec</a> and the <a href="https://github.github.com/gfm/">GitHub spec</a> for details.</p>

The label is case-insensitive and can appear before or after the reference. The definition line does not render in the output; it only supplies the URL. You can add a title to a reference definition too: [cm]: https://spec.commonmark.org "CommonMark".

Implicit and collapsed reference links

If the link text and the label are the same, you can collapse the label to empty brackets, or omit the second set of brackets entirely.

Markdown

The [CommonMark][] spec and the [GFM] spec.

[CommonMark]: https://spec.commonmark.org
[GFM]: https://github.github.com/gfm/

Rendered output

Autolinks with angle brackets

To turn a bare URL into a link, wrap it in angle brackets. This is the portable way to autolink because it works in strict parsers that do not detect bare URLs on their own. Email addresses in angle brackets become mailto: links.

Markdown

Homepage: <https://markdific.com>
Contact: <[email protected]>

Rendered output

HTML output

<p>Homepage: <a href="https://markdific.com">https://markdific.com</a>
Contact: <a href="mailto:[email protected]">[email protected]</a></p>

Some flavors, notably GitHub Flavored Markdown and Pandoc with an extension, also turn a bare URL into a link without the angle brackets. That behavior is not universal, so angle-bracket autolinks are the safe choice. Bare URL autolinking has its own page: see automatic links.

Relative versus absolute URLs

A link can point to an absolute URL, which includes the scheme and domain, or a relative URL, which is resolved against the current page. Relative links are useful for linking between pages in the same site or repository.

Markdown

Absolute: [home](https://markdific.com/)
Relative: [the code page](/docs/markdown/code/)

Rendered output

HTML output

<p>Absolute: <a href="https://markdific.com/">home</a>
Relative: <a href="/docs/markdown/code/">the code page</a></p>

A relative link starting with a slash is resolved from the site root. A relative link without a slash is resolved from the current page's directory. Choose based on how your content is deployed.

Links wrapping images

You can make an image clickable by placing image syntax inside the link text. The result is an image wrapped in an anchor, so clicking the image follows the link.

Markdown

[![Markdific logo](/assets/logo-markdific-v1-transparent-ti.png "Markdific")](https://markdific.com)

Rendered output

HTML output

<p><a href="https://markdific.com"><img src="/assets/logo-markdific-v1-transparent-ti.png" alt="Markdific logo" title="Markdific"></a></p>

The image's alt text still describes the image, while the outer link controls where a click goes. For more on the image half of this pattern, see images.

Flavor differences

Inline links, titles, reference-style links, and angle-bracket autolinks are part of the original Markdown syntax and are broadly supported. The main flavor difference is whether a bare URL, with no angle brackets, becomes a link automatically.

Reference-style links behave the same across all five flavors: define a label once and reuse it. The one meaningful difference is bare URL autolinking, which is on by default only in GFM and opt-in in Pandoc.

Other platforms (Slack, Discord, Reddit, Notion)

Chat and note tools handle links with their own quirks:

• Slack: the standard [text](url) syntax is not supported in messages. Slack auto-links bare URLs and lets you attach display text through its own link editor, not Markdown.
• Discord: bare URLs auto-link, and the [text](url) inline syntax works in some surfaces but not in plain messages. Behavior differs between the message box and embeds.
• Reddit: supports inline [text](url) links and reference-style links in the Markdown editor. Bare URLs also auto-link.
• Notion: supports [text](url) while typing, converting it to a link, but does not use reference-style link definitions.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific renders links as clickable anchors, with reference-style definitions resolved into their target URLs and angle-bracket autolinks turned into links. A link that wraps an image renders as a clickable inline image, since Markdific renders inline images.

Try it in the Markdific online editor.

Common mistakes and gotchas

• Space between the brackets and parentheses. [text] (url) breaks the link. The ]( must be adjacent with no space.
• Unescaped spaces in the URL. A space inside the parentheses ends the URL early. Wrap the URL in angle brackets, like [text](<url with space>).
• Missing reference definition. A reference link with no matching definition renders as literal text, brackets and all.
• Wrong quote for the title. The title must be inside quotes or parentheses, separated from the URL by a space. Missing the space merges the title into the URL.
• Assuming bare URLs always link. Only some flavors auto-link bare URLs. Use angle brackets for a portable autolink.
• Reversing image and link order. To make an image clickable, the image goes inside the link text: [![alt](img)](url), not the other way around.
• Relative link resolving from the wrong place. A relative link without a leading slash resolves from the current directory, which can surprise you after a page moves.

Best practices

• Use inline links for one-off references and reference-style links when the same URL repeats or when URLs are long.
• Write descriptive link text that makes sense out of context. Avoid "click here."
• Add a title only when it gives real extra information, since titles are not visible to every reader.
• Prefer angle-bracket autolinks over bare URLs for portability across flavors.
• Use root-relative links (starting with a slash) for internal site links so they survive page moves.
• When linking an image, keep the alt text meaningful and let the link control the destination.

HTML equivalent

Every Markdown link compiles to an HTML anchor element. Inline links, reference-style links, and autolinks all produce the same <a> element; only the source syntax differs.

Markdown

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

<https://example.com>

HTML output

<p><a href="https://example.com" title="Title">text</a></p>
<p><a href="https://example.com">https://example.com</a></p>

FAQ

How do you create a link in Markdown? Put the link text in square brackets followed immediately by the URL in parentheses, like [text](https://example.com). There must be no space between the closing bracket and the opening parenthesis.

How do you add a title to a Markdown link? Place a quoted string after the URL, separated by a space, like [text](https://example.com "Title"). The title becomes the anchor's title attribute and usually shows as a tooltip.

What is a reference-style link in Markdown? A reference-style link separates the text from the URL. You label the text with [text][id] and define the URL once with [id]: https://example.com. The definition does not appear in the output.

How do you make a bare URL clickable in Markdown? Wrap it in angle brackets, like <https://example.com>. This is defined by CommonMark and supported by most modern Markdown renderers. Some flavors, such as GitHub Flavored Markdown, also link bare URLs without brackets, but that is not universal.

Can you make an image a link in Markdown? Yes. Put the image syntax inside the link text: [![alt](image.png)](https://example.com). Clicking the image follows the outer link.

What is the difference between a relative and an absolute link? An absolute link includes the full scheme and domain. A relative link is resolved against the current page. A relative link starting with a slash resolves from the site root.

Why is my Markdown link showing as plain text? Common causes are a space between the brackets and parentheses, a space in an unescaped URL, or a reference link with no matching definition. Check each of these.

What HTML does a Markdown link produce? Every link form produces an anchor element with an href attribute, plus a title attribute when a title is given. Inline, reference, and autolink syntaxes all compile to the same anchor.

How do you open a Markdown link in a new tab? Core Markdown has no syntax for the target attribute. Where inline HTML is allowed, write a raw anchor tag such as <a href="https://example.com" target="_blank" rel="noopener">text</a>. This is not portable, because some renderers strip the attribute.

How do you link to a heading on the same page in Markdown? Link to the heading's anchor with a hash and its slug, like [jump to setup](#setup). Most renderers generate an id for each heading by lowercasing the text and replacing spaces with hyphens. See heading IDs for the exact rules.

How do you write an email link in Markdown? Wrap the address in angle brackets, like <[email protected]>, which becomes a mailto: link automatically. For custom link text, use the inline form with an explicit mailto URL, such as [email us](mailto:[email protected]).

Can Markdown link text contain bold, italic, or code? Yes. The text inside the square brackets accepts inline formatting, so [**bold link**](https://example.com) and [codelink](https://example.com) both work. The formatting renders inside the anchor.

Sources and compatibility references

• CommonMark 0.31.2: links
• Google: link best practices

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Images in Markdown
• Automatic links
• Escaping characters
• Code in Markdown
• Markdown flavors compared