ShareGPT

Here is a summary of the usual ways of using references (reference-style links) in CommonMark (standard Markdown). This lets you separate link text from link destinations, making source text cleaner and easier to maintain.

🔹 Main reference-link syntax in CommonMark

Link reference definitions

You first define a “label → URL (and optional title)” somewhere in the document (before or after links that use it). The general form is:

[my-label]: https://example.com/ "Optional title"

• The line must start with a label in square brackets (optionally preceded by up to three spaces), followed by a colon (:), then the URL (destination), optionally a title in quotes. (spec.commonmark.org)
• These do not correspond to visible output themselves, they just define a mapping used by reference-style links. (spec.commonmark.org)
• Definitions can appear either before or after their usage. (spec.commonmark.org)

Using the references in link text

Once defined, you can use these references elsewhere as follows:

• Full reference link:

  [Link text][my-label]
  

  This creates a link whose displayed text is “Link text” and which points to the URL defined under my-label. (spec.commonmark.org)

• Collapsed reference link (shortcut for when displayed text equals the label):

  [my-label][]
  

  This displays “my-label” and links to its definition. (spec.commonmark.org)

• Shortcut reference link (simplest form, also when label = link text):

  [my-label]
  

  CommonMark treats this as a reference link — but only if there is a matching definition. Label matching is done on a normalized version (case-folded, internal whitespace collapsed). (spec.commonmark.org)

Precedence and corner cases

• Inline links (the form [text](URL "title")) take precedence over reference links. So if you write [foo](), even if foo has a reference definition, that will be treated as empty inline link, not reference link. (spec.commonmark.org)
• If there are multiple definitions for the same label, only the first (earliest) is used. (spec.commonmark.org)
• Link labels cannot have unescaped brackets (unless backslash-escaped). (spec.commonmark.org)

✳️ Why / When It’s Useful

• Reference-style links help keep the main body of Markdown more readable, especially when linking to long or complex URLs.
• They are useful when the same link (URL) is referenced multiple times with different link text: define once, reuse many times.
• They make editing/moving links easier: you only need to update URL in the definition, not every occurrence.

✅ Example of a full pattern

Here’s a small example combining definitions and use:

Here’s an introduction to [Markdown documentation][cm].

More reading: see [CommonMark spec][cm].

[cm]: https://spec.commonmark.org/0.29/ "CommonMark — Specification"

This will render two identical links (“Markdown documentation” and “CommonMark spec”) both pointing to the same URL, with title attribute “CommonMark — Specification.”