Reference Links
An inline link bundles the visible text and the address into one piece of markup, which is fast to write and pleasant to read. The moment the same address appears ten times, though, those ten occurrences each carry their own copy of it: change the domain once and you have to find ten places to change it, miss one, and the page quietly keeps pointing at the old site.
Reference links solve that by splitting the link in two. The body of the text contains only a short label, and the addresses are collected into definitions that live in one place. This page takes the mechanism apart — the definition, the reference, and the two shorthands that remove the repeated characters — and then asks the question that matters in practice: when is this extra machinery worth it, and when is it just indirection?
A reference link is made of a reference in the text and a definition somewhere in the file. In the text you write square brackets around the visible text and square brackets again around a label. In the definitions you write the label, a colon, the address, and optionally a title:
[Documentation home][home]
[Search engine][google]
[home]: https://example.com
[google]: https://google.com<p><a href="https://example.com">Documentation home</a>
<a href="https://google.com">Search engine</a></p>The label is the join between the two halves. It is an internal name that never reaches the page: the reader sees the visible text and clicks the link, and the definition itself stays invisible.
Labels are matched without regard to case, so [Docs][HOME] and [home]: ... refer to each other. That is convenient, but it also means that two labels differing only in case are the same label — a trap worth knowing before you name two different destinations Home and home.
The Two Shorthands
When the visible text happens to be the label itself, the second pair of brackets can be emptied — the collapsed form — or dropped entirely — the shortcut form:
[home][] and [home]
[home]: https://example.com<p><a href="https://example.com">home</a> and <a href="https://example.com">home</a></p>Both render exactly like the full form; they only change how many characters you type. The collapsed form keeps the brackets, which makes the position of the link obvious when you skim the source. The shortcut form is the shortest, but it carries a real cost: the label has to look like a link, or a reader working through the source has no way of telling home — a link — from sidebar — a word.
The Definition Carries the Title
The optional title belongs to the definition rather than to the reference:
[Documentation home][home]
[home]: https://example.com "The project home page"<p><a href="https://example.com" title="The project home page">Documentation home</a></p>This is the one structural advantage the reference form has over the inline form: change the title or the address in one place and every reference pointing at that definition changes with it.
A definition may sit anywhere in the file. The parser scans the whole document before it renders anything, so a definition near the top can serve a reference at the very bottom. The convention, and the one worth following, is to collect them at the end of the file or in a dedicated section at the end:
Body text with [a reference][home].
## References
[home]: https://example.comThe definitions never appear in the rendered output. They are data for the parser, not content for the reader, which is exactly why they can be moved around without disturbing the prose.
The payoff of the reference form is reuse. A single definition can back any number of references, and the visible text may differ every time:
Read the [home page][home], or open the [home page][home] again while you
follow the [walkthrough][home].
[home]: https://example.com<p>Read the <a href="https://example.com">home page</a>, or open the <a href="https://example.com">home page</a> again while you
follow the <a href="https://example.com">walkthrough</a>.</p>The visible text is free, so the same destination can be described differently in different places — home page in one sentence, walkthrough in the next — while the address itself is written exactly once.
Relative paths inside a definition are resolved against the directory of the file that holds the definition. In an ordinary single-file document that is the same rule an inline link follows, so moving a page and its definitions together keeps the link working.
Reference links earn their keep in three situations. The first is repetition, when the same destination appears more than two or three times. The second is concentration, when a document cites a dozen external sources and is easier to audit when every address sits in one block. The third is an address that would wreck the sentence it sits in: a long URL with a query string reads terribly inline, and reads perfectly as [the API reference][api].
They have costs too. The reader can no longer see where a link points without scrolling to the end of the document, which matters when the address itself is the information — a download, an API endpoint, an email address. And the extra indirection gives you one more thing to keep in sync: the label.
| Written as | What actually happens | Why |
|---|---|---|
[text][ref] with [ref]: https://x.com | A link | The full form |
[ref][] with [ref]: https://x.com | A link | The collapsed form |
[ref] with [ref]: https://x.com | A link | The shortcut form |
[text][missing] | Plain text | No definition carries that label |
| A definition indented by four spaces | A code block | Indented code wins over the definition syntax |
[text][REF] with [ref]: https://x.com | A link | Labels are matched case-insensitively |
| A definition indented by two spaces | A link | Indented code needs four spaces |
A label that does not match its definition fails silently. Misspell the label, or delete a definition while a reference still points at it, and the page reports no error: the reference is simply left as ordinary text, brackets and all, so the reader assumes the author wrote it that way. Before removing a definition, search the document for its label, and when a link mysteriously stops being a link, check the label before anything else.
Rewrite the following paragraph as Markdown. Requirements: all three links must use the reference form, with the label written inside the brackets; put the three definitions together at the end of the document; and write the link to the search service in the shortcut form, because its visible text and its label are the same.
Please visit the documentation home on example.com, look at the search service on search.example.org, and check the example repository on github.com.Approach:
A reference link is a label in the text plus a definition elsewhere in the file. The three destinations are different, so each needs its own label. For the search service the visible text and the label coincide, so the shortcut form — a single pair of brackets around the label — is enough.
Steps:
- Give each destination a short label:
home,search,repo. A label is an internal name; it never appears on the page. - Write the references. The documentation home becomes
[the documentation home][home], the search service becomes[search], and the example repository becomes[the example repository][repo]. - Write the three definitions at the end, one per line: the label in square brackets, a colon, a space, then the address. The lines must start at the left margin — indenting them by four spaces turns them into a code block instead of definitions.
- Check the result: the three references render as links, the definitions do not appear on the page, and the shortcut reference is still clickable.
Answer:
Please visit the [documentation home][home], look at the [search] service, and check the [example repository][repo].
[home]: https://example.com
[search]: https://search.example.org
[repo]: https://github.comYou should now be able to write the full, collapsed, and shortcut forms of a reference link, keep the definitions together at the end of the file, reuse one definition across many references, explain why labels are matched without regard to case, and say why an indented definition stops being a definition. You should also be able to recognise the quiet failure mode: a link that is no longer a link because its label no longer matches anything. The next page moves to the other member of the family — images, which use the same syntax with one extra character in front.