Automatic Links
The two link forms covered so far both ask you to write two things: the visible text and the address. Sometimes that is exactly what you want. Sometimes it is redundant, because the text you would display is the address, and writing it twice is noise. And sometimes you have no idea what the text should say, because there is no text — there is just an address that a reader needs to copy.
Markdown has a third answer for those cases: it can recognise an address on its own and turn it into a link. There are two mechanisms for this, they belong to different levels of the specification, and they behave differently enough that you need to know both. This page also pins down something the syntax never states in so many words — where an automatic link stops — because that boundary is the source of nearly every surprise in this area.
Wrap the address in angle brackets and it becomes a link whose visible text is the address itself:
<https://example.com>
<user@example.com><p><a href="https://example.com">https://example.com</a>
<a href="mailto:user@example.com">user@example.com</a></p>The email address gains a mailto: prefix automatically, so clicking it opens a new message with the address already filled in. The scheme of a web address is left exactly as you wrote it, and a mailto: prefix may also be written out by hand when you want it visible.
This form is the most predictable of everything in this chapter: what you type is what the reader gets, with no conversion in between and no parsing rules to remember. It is part of CommonMark, so every renderer supports it, and it is the form to reach for whenever the address has to be exactly right.
Writing the Scheme by Hand
The mailto: prefix may also be written out, which is useful when you want the reader to see that the link opens a mail client rather than a web page:
<mailto:user@example.com><p><a href="mailto:user@example.com">mailto:user@example.com</a></p>The target is the same either way; only the visible text differs, because the text of an automatic link is always the address you wrote.
GitHub Flavored Markdown adds a more relaxed rule: an address written directly in the prose becomes a link, with no markup at all.
Visit https://example.com for more, or contact user@example.com.<p>Visit <a href="https://example.com">https://example.com</a> for more, or contact <a href="mailto:user@example.com">user@example.com</a>.</p>The literal form has requirements. An address must begin with http:// or https://, or with the www. prefix, which GFM completes to http:// for you. A bare host name is not recognised:
Bare www.example.com and example.com here.<p>Bare <a href="http://www.example.com">www.example.com</a> and example.com here.</p>The second one is plain text, because it has neither a scheme nor the www. prefix. That difference matters when a renderer does not implement GFM at all: a CommonMark-only renderer treats every bare address in this section as ordinary text, including the ones that look like links here. The angle-bracket form is the portable one, and the literal form is the convenient one.
Nothing in the syntax tells you this, so it is worth stating plainly: an automatic link ends at the first space or at the first ASCII punctuation mark. Everything else — letters, digits, and every non-ASCII character — is treated as part of the address.
That rule explains the behaviour you are most likely to meet. English punctuation closes the address and stays outside the link:
See https://example.com. and https://example.com/a)<p>See <a href="https://example.com">https://example.com</a>. and <a href="https://example.com/a">https://example.com/a</a>)</p>But a character that merely looks like punctuation is not ASCII punctuation, so it is pulled into the address instead. The em dash is the everyday example: write an address and an em dash next to each other, and the dash becomes part of the link target, percent-encoded, while the visible text still reads as one long address.
The same rule cuts the other way when a space is missing. An address written straight into the next word becomes a link to something longer than you intended, and a space inside an address ends the link early and leaves the tail as loose text on the page.
An automatic link is recognised wherever inline content is allowed — in the middle of a sentence, inside a list item, inside a table cell, inside a quotation:
Read the guide at https://example.com/guide for the setup steps.
> The status page is https://example.com/status and it is refreshed every hour.<p>Read the guide at <a href="https://example.com/guide">https://example.com/guide</a> for the setup steps.</p>
<blockquote>
<p>The status page is <a href="https://example.com/status">https://example.com/status</a> and it is refreshed every hour.</p>
</blockquote>What the container changes is only the surroundings: the address still ends at the first space, and the same rules apply inside a table cell as in a paragraph.
The automatic form is the shortest way to publish an address, and it has one large advantage: the reader sees the real address, can select it, can copy it, and can type it into another program without touching the mouse. That matters for a download, an API endpoint, a command someone is supposed to run, or an email address they are expected to write to.
What it gives up is control. The visible text is fixed — it is the address — so a long URL with a query string becomes an unwieldy run of text in the middle of a sentence. There is no title, because there is nowhere to put one. And the boundary is chosen by the parser rather than by you.
The explicit forms give exactly the opposite: the text is yours to write, the address is yours to write, and the boundary is where you put it. The cost is the extra characters, and the loss of a copyable raw address in the visible text. A practical split follows from that: use an automatic link when the address itself is the message, and an explicit link when the address is really a citation.
| Written as | What actually happens | Why |
|---|---|---|
<https://example.com> | A link | The angle-bracket form, with an exact boundary |
https://example.com | A link | A GFM literal autolink |
www.example.com | A link to http://www.example.com | GFM completes a www. host with http:// |
example.com | Plain text | No scheme, and not a www. host |
https://example.com. | A link without the full stop | ASCII punctuation ends the address |
https://example.com— | A link that includes the dash | Only ASCII punctuation ends the address |
https://example.com/a b | A link to the first fragment | A space ends the address |
The end of an automatic link is decided by the parser, not by you. An address stops at the first space or the first ASCII punctuation mark, and everything else is swallowed into it — including punctuation that is not ASCII, such as an em dash, which becomes part of the link target and is percent-encoded there. That is why a missing space turns https://example.com/status and the following word into a link to a completely different address. When the boundary has to be exact, wrap the address in angle brackets: the link then ends precisely where you closed the bracket, and nothing can be added to it by accident.
Rewrite the following paragraph as Markdown. Requirements: the first address must use the angle-bracket form, so that its boundary is exact; the second address must use the GFM literal form, and the em dash that follows it must not become part of the link; and the email address may use either form, as long as clicking it opens a new message.
The manual lives at https://example.com/docs — read it before you start. The status page is https://example.com/status—refreshed every hour. Contact the maintainers at maintainers@example.com.Approach:
The two forms differ in who decides where the link ends. The angle-bracket form ends the link exactly at the closing bracket, so it is the safe choice when the address is followed by something unusual. The GFM literal form ends the link at the first space or the first ASCII punctuation mark, so an em dash placed directly after the address is swallowed into it. In that case the fix is a space, because a space always terminates the address.
Steps:
- Write the first address in the angle-bracket form:
https://example.com/docsbetween angle brackets. The link then ends at the bracket and the em dash and the rest of the sentence stay in the prose. - Write the second address in the GFM literal form, with no markup. Separate it from the em dash with a space so that the address ends at the space and the dash is left outside the link.
- Write the email address in the angle-bracket form. The
mailto:prefix is added automatically, so clicking it opens a new message. - Check the result: three links, three correct targets, and the sentence after the first address and the dash after the second one both remain readable text rather than being folded into a link.
Answer:
The manual lives at <https://example.com/docs> — read it before you start. The status page is https://example.com/status — refreshed every hour. Contact the maintainers at <maintainers@example.com>.You should now be able to write an automatic link in the angle-bracket form and explain why it is the portable one, write one in the GFM literal form and say what a scheme is for, tell a www. host apart from a bare host name, and state the boundary rule in full: an automatic link ends at the first space or the first ASCII punctuation mark. You should also be able to spot the two classic failures — a word glued to the end of an address, and a non-ASCII punctuation mark pulled into it — and to say why an explicit link is the better choice when the address is a citation rather than the message. That completes the chapter on links and images; the next one moves on to the block-level structures that hold a long document together.