Libx CommonMark Basics and Leaf Blocks

    On this page

    A link reference definition consists of a link label, optionally preceded by up to three spaces of indentation, followed by a colon (:), optional spaces or tabs (including up to one line ending), a link destination, optional spaces or tabs (including up to one line ending), and an optional link title, which if it is present must be separated from the link destination by spaces or tabs. No further character may occur.

    A link reference definition does not correspond to a structural element of a document. Instead, it defines a label which can be used in reference links and reference-style images elsewhere in the document. Link reference definitions can come either before or after the links that use them.

    Example 192 
    [foo]: /url "title"

[foo]

    <p><a href="/url" title="title">foo</a></p>
    Example 193 
       [foo]: 
      /url  
           'the title'  

[foo]

    <p><a href="/url" title="the title">foo</a></p>
    Example 194 
    [Foo*bar\]]:my_(url) 'title (with parens)'

[Foo*bar\]]

    <p><a href="my_(url)" title="title (with parens)">Foo*bar]</a></p>
    Example 195 
    [Foo bar]:
<my url>
'title'

[Foo bar]

    <p><a href="my%20url" title="title">Foo bar</a></p>

    The title may extend over multiple lines:

    Example 196 
    [foo]: /url '
title
line1
line2
'

[foo]

    <p><a href="/url" title="
title
line1
line2
">foo</a></p>

    However, it may not contain a blank line:

    Example 197 
    [foo]: /url 'title

with blank line'

[foo]

    <p>[foo]: /url 'title</p>
<p>with blank line'</p>
<p>[foo]</p>

    The title may be omitted:

    Example 198 
    [foo]:
/url

[foo]

    <p><a href="/url">foo</a></p>

    The link destination may not be omitted:

    Example 199 
    [foo]:

[foo]

    <p>[foo]:</p>
<p>[foo]</p>

    However, an empty link destination may be specified using angle brackets:

    Example 200 
    [foo]: <>

[foo]

    <p><a href="">foo</a></p>

    The title must be separated from the link destination by spaces or tabs:

    Example 201 
    [foo]: <bar>(baz)

[foo]

    <p>[foo]: <bar>(baz)</p>
<p>[foo]</p>

    Both title and destination can contain backslash escapes and literal backslashes:

    Example 202 
    [foo]: /url\bar\*baz "foo\"bar\baz"

[foo]

    <p><a href="/url%5Cbar*baz" title="foo&quot;bar\baz">foo</a></p>

    A link can come before its corresponding definition:

    Example 203 
    [foo]

[foo]: url

    <p><a href="url">foo</a></p>

    If there are several matching definitions, the first one takes precedence:

    Example 204 
    [foo]

[foo]: first
[foo]: second

    <p><a href="first">foo</a></p>

    As noted in the section on Links, matching of labels is case-insensitive (see matches).

    Example 205 
    [FOO]: /url

[Foo]

    <p><a href="/url">Foo</a></p>
    Example 206 
    [ΑΓΩ]: /φου

[αγω]

    <p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>

    Whether something is a link reference definition is independent of whether the link reference it defines is used in the document. Thus, for example, the following document contains just a link reference definition, and no visible content:

    Example 207 
    [foo]: /url

    Here is another one:

    Example 208 
    [
foo
]: /url
bar

    <p>bar</p>

    This is not a link reference definition, because there are characters other than spaces or tabs after the title:

    Example 209 
    [foo]: /url "title" ok

    <p>[foo]: /url &quot;title&quot; ok</p>

    This is a link reference definition, but it has no title:

    Example 210 
    [foo]: /url
"title" ok

    <p>&quot;title&quot; ok</p>

    This is not a link reference definition, because it is indented four spaces:

    Example 211 
        [foo]: /url "title"

[foo]

    <pre><code>[foo]: /url &quot;title&quot;
</code></pre>
<p>[foo]</p>

    This is not a link reference definition, because it occurs inside a code block:

    Example 212 
    ```
[foo]: /url
```

[foo]

    <pre><code>[foo]: /url
</code></pre>
<p>[foo]</p>

    A link reference definition cannot interrupt a paragraph.

    Example 213 
    Foo
[bar]: /baz

[bar]

    <p>Foo
[bar]: /baz</p>
<p>[bar]</p>

    However, it can directly follow other block elements, such as headings and thematic breaks, and it need not be followed by a blank line.

    Example 214 
    # [Foo]
[foo]: /url
> bar

    <h1><a href="/url">Foo</a></h1>
<blockquote>
<p>bar</p>
</blockquote>
    Example 215 
    [foo]: /url
bar
===
[foo]

    <h1>bar</h1>
<p><a href="/url">foo</a></p>
    Example 216 
    [foo]: /url
===
[foo]

    <p>===
<a href="/url">foo</a></p>

    Several link reference definitions can occur one after another, without intervening blank lines.

    Example 217 
    [foo]: /foo-url "foo"
[bar]: /bar-url
  "bar"
[baz]: /baz-url

[foo],
[bar],
[baz]

    <p><a href="/foo-url" title="foo">foo</a>,
<a href="/bar-url" title="bar">bar</a>,
<a href="/baz-url">baz</a></p>

    Link reference definitions can occur inside block containers, like lists and block quotations. They affect the entire document, not just the container in which they are defined:

    Example 218 
    [foo]

> [foo]: /url

    <p><a href="/url">foo</a></p>
<blockquote>
</blockquote>