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 ecbb8c7
Showing 1 changed file with 129 additions and 11 deletions.
140 changes: 129 additions & 11 deletions spec.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3467,16 +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 +3475,6 @@ can occur one after another, without intervening blank lines.
[bar]: /bar-url
"bar"
[baz]: /baz-url

[foo],
[bar],
[baz]
Expand All @@ -3495,6 +3484,120 @@ can occur one after another, without intervening blank lines.
<a href="/baz-url">baz</a></p>
````````````````````````````````

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]:
#
[foo]
.
<p>[foo]:</p>
<h1></h1>
<p>[foo]</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>
````````````````````````````````

Both of 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
Expand All @@ -3511,6 +3614,21 @@ are defined:
</blockquote>
````````````````````````````````

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

Expand Down

0 comments on commit ecbb8c7

Please sign in to comment.