Skip to content

Commit

Permalink
clarify link reference definition interruptions and continuation text
Browse files Browse the repository at this point in the history
Other blocks can interrupt a link reference definition,
and link reference definitions can have continuation text
that is not fully prefixed, following the rules of paragraph
continuation text.

Document both these facts and give examples.

Fixes commonmark#688.
  • Loading branch information
rsc committed Sep 4, 2021
1 parent 499ebba commit c3b0c63
Showing 1 changed file with 137 additions and 10 deletions.
147 changes: 137 additions & 10 deletions spec.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3467,15 +3467,6 @@ bar
<p><a href="/url">foo</a></p>
````````````````````````````````

```````````````````````````````` example
[foo]: /url
===
[foo]
.
<p>===
<a href="/url">foo</a></p>
````````````````````````````````


Several [link reference definitions]
can occur one after another, without intervening blank lines.
Expand All @@ -3485,7 +3476,6 @@ can occur one after another, without intervening blank lines.
[bar]: /bar-url
"bar"
[baz]: /baz-url

[foo],
[bar],
[baz]
Expand All @@ -3496,6 +3486,126 @@ can occur one after another, without intervening blank lines.
````````````````````````````````


The text of a [link reference definition] can be interrupted by any block element
that can interrupt a paragraph. These are not definitions at all,
because what would be a multi-line title is interrupted
by a heading, quoted text, and a fenced code block:

```````````````````````````````` example
[foo]: /url '
# h1
'

[foo]: /url '
> quote
'

[foo]: /url '
```
text
```
'

[foo]
.
<p>[foo]: /url '</p>
<h1>h1</h1>
<p>'</p>
<p>[foo]: /url '</p>
<blockquote>
<p>quote
'</p>
</blockquote>
<p>[foo]: /url '</p>
<pre><code>text
</code></pre>
<p>'</p>
<p>[foo]</p>
````````````````````````````````


This isn't a two-line definition because the list interrupts the title,
leaving a one-line definition:

```````````````````````````````` example
[foo]: /url
'
- list item
'

[foo]
.
<p>'</p>
<ul>
<li>list item
'</li>
</ul>
<p><a href="/url">foo</a></p>
````````````````````````````````


It is also possible for the URL itself to be interrupted:

```````````````````````````````` example
[foo]:
#
[bar]: #
[foo] [bar]
.
<p>[foo]:</p>
<h1></h1>
<p>[foo] <a href="#">bar</a></p>
````````````````````````````````


Because an indented code block cannot interrupt a paragraph,
it also cannot interrupt a [link reference definition]:

```````````````````````````````` example
[foo]: /url '
not a code block
'

[foo]
.
<p><a href="/url" title="
not a code block
">foo</a></p>
````````````````````````````````


These are valid [link reference definitions],
leaving no text for `===` to create a setext heading:

```````````````````````````````` example
[foo]: /url
===
[foo]
.
<p>===
<a href="/url">foo</a></p>
````````````````````````````````

```````````````````````````````` example
[foo]: /url 'bar'
===
[foo]
.
<p>===
<a href="/url" title="bar">foo</a></p>
````````````````````````````````

```````````````````````````````` example
[foo]: /url
'bar'
===
[foo]
.
<p>===
<a href="/url" title="bar">foo</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
Expand All @@ -3512,6 +3622,23 @@ are defined:
````````````````````````````````


The text in a link reference definition can be continued
using the same rules as for [paragraph continuation text]:

```````````````````````````````` example
> [foo]: /url '
hello
'
> [foo]
.
<blockquote>
<p><a href="/url" title="
hello
">foo</a></p>
</blockquote>
````````````````````````````````


## Paragraphs

A sequence of non-blank lines that cannot be interpreted as other
Expand Down

0 comments on commit c3b0c63

Please sign in to comment.