Reference-Style Links

Inline link syntax — [text](url) — gets unwieldy when you reuse the same URL many times or when URLs are long. The reference style separates the link text from the URL definition:

See the [Python docs][py] and the [Python source][py].

[py]: https://docs.python.org/3/

Both [Python docs][py] and [Python source][py] resolve to <a href="https://docs.python.org/3/">...</a>.

Three variants

• Full: [text][label]
• Collapsed: [label][] (uses label as both text and lookup key)
• Shortcut: [label] (only when no other meaning is possible)

The label lookup is case-insensitive and trims surrounding whitespace.

Reference definitions A reference definition has the form [label]: url on its own line. It can appear ANYWHERE in the document — before or after the links that use it. This is why most parsers do a pre-pass: extract every [label]: url line first, build a dict, then render the document.

Implementation pattern

This is one of the few places where Markdown requires out-of-order resolution — a link can refer to a label defined LATER in the document. Treat your block phase as the place to extract references, and your inline phase as the place to resolve them.