Link reference definitions woes

dbuenzli · November 30, 2022, 3:06pm

The specification talks a bit what can or cannot come before a link reference definition, but less about what can come after.

For example I fail to understand this rendering:

[foo]: /ha 
    bla

which is (and consistently with cmark and md2html):

<p>bla</p>

I would have expected an indented code block to be rendered. Similarly this rendering:

[foo]: /ha
---

Yields in the dingus:

<p></p>
<hr />

I would have expected a simple <hr />. Also both cmark and md2html render this as:

<p>---</p>

(my impression is the cmark and md2html’s behaviour is an artefact of their implementations, which is to gather a paragraph, peel any initial sequence of link reference definitions and treat the remains as a paragraph).

So what are the rules that govern the behaviour for what comes after a link reference definition ?

jgm · November 30, 2022, 4:21pm

Yes, you’re right, these things are a result of an implementation shortcut:

github.com/commonmark/commonmark-spec

Mention that link reference definitions are constructed from paragraphs

opened 01:29PM - 11 Sep 19 UTC

wooorm

### Problem According to the spec text: ```markdown [ ␠␠␠␠# a ␠␠␠␠b ␠␠…␠␠]: ␠␠␠␠example.com ' ␠␠␠␠line1 ␠␠␠␠... ␠␠␠␠' ``` ...is fine: it’s a proper link reference definition. This lead me to believe that true streaming, as noted in [§ Appendix ¶ Phase 1](https://spec.commonmark.org/0.29/#phase-1-block-structure), wouldn‘t work because if the last apostrophe wasn’t there, we’d need to backtrack (to the start because the opening apostrophe is on the line of the destination, if it was on its own line, the definition would be valid but we’d still need to backtrack to parse the title again). To my surprise, the following is not a link reference definition (note one less space before `a`) ```markdown [ ␠␠␠# a ␠␠␠␠b ␠␠␠␠]: ␠␠␠␠example.com ' ␠␠␠␠line1 ␠␠␠␠... ␠␠␠␠' ``` ...`# a` is now a heading! Only then did I see that the Appendix contains: > Reference link definitions are detected when a paragraph is closed; the accumulated text lines are parsed to see if they begin with one or more reference link definitions. Any remainder becomes a normal paragraph. ### Solution I think it’s good to mention in the main text that link reference definitions are created from paragraphs, and include a test for it. Not entirely sure how to describe this though. This will also help prevent blank lines that are currently possible in labels (GH-586) #### Extra As paragraph lines are made into actual paragraphs and definitions, setext heading lines come into play, so relating to GH-395, I think the following may also be interesting to expand upon: ``` [foo]: /url 'alpha = bravo' [foo] ``` Dingus: ```html <h1>'alpha</h1> <p>bravo'</p> <p><a href="/url">foo</a></p> ```

I agree that the spec doesn’t define this precisely enough. The cmark behavior is to treat the following lines as they’d be treated if parsed as continuation lines in a paragraph. So e.g.

% cmark
ha
 1. blah
^D
<p>ha</p>
<ol>
<li>blah</li>
</ol>

but

% cmark
[foo]: ha
 2. blah
<p>2. blah</p>

(Remember that only ordered lists starting with 1 can interrupt a paragraph.)

Similarly in

[foo]: /ha
    bla

we don’t have a code block for the same reason that we don’t in

foo
    bla

I think this is reasonable behavior and maybe it should be enshrined in the spec. But comments welcome. The empty <p> in the JavaScript implementation can be regarded as a bug.

dbuenzli · November 30, 2022, 4:56pm

Thanks for our answers.

Apparently there’s already an issue filed for it.

I have a conflict of interest in being for this so I’ll refrain from commenting :–) but I think it would be nice if there was a common behaviour for parsers on these (likely) corner cases.

P.S. I forgot to add the spec tag when I posted this other topic but it is also a request for clarification of the spec. If you have time to have a look at it that would be great.