Increase Precedence of shortcut link references over full and compact for defined link references

[theory]

Followup to this discussion as well as yuin/goldmark#143. The idea is to give higher precedence to shortcut link references when they actually resolve to a link defined in the document, so as to give priority to the links as defined by the author, rather than to the rules for parsing the links references themselves. Where ambiguity cannot be resolved by link definitions, the precedence should be as before. Examples follow.

Example 561

[foo][bar]

[foo]: /url1
[bar]: /url2

Current output:

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

Desired output:

<p><a href="/url1">foo</a><a href="/url2">bar</a></p>

Reason: The author has made explicit definitions for the foo and bar links, so both should take precedence over [foo][bar], as it's more likely to reflect the author's intent.

Example 567

[foo][bar][baz]

[baz]: /url1
[foo]: /url2

Current output:

<p>[foo]<a href="/url1">bar</a></p>

Desired output:

<p><a href="/url2">foo</a><a href="/url1">bar</a></p>

Reason: The author has made explicit definitions for the baz and foo links but not bar, so [foo] and [bar] should take precedence over [bar][baz], as it's more likely to reflect the author's intent.

Footnote Example

Visit [Foo][^1].

  [Foo]: https://example.com/
  [^1]: But not really

Current output:

<p>Visit [Foo]<sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup>.</p>
<hr class="footnotes-sep">
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn1" class="footnote-item"><p>But not really <a href="#fnref1" class="footnote-backref">↩︎</a></p>
</li>
</ol>
</section>

Desired output:

<p>Visit <a href="https://example.com/">Foo</a><sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup>.</p>
<hr class="footnotes-sep">
<section class="footnotes">
<ol class="footnotes-list">
<li id="fn1" class="footnote-item"><p>But not really <a href="#fnref1" class="footnote-backref">↩︎</a></p>
</li>
</ol>
</section>

Reason: The author has made explicit definitions for both the [Foo] link and the [^1] footnote, so both should be rendered, rather than prioritizing [Foo][^1] as a full reference, especially since [^1] fails to resolve to a link at all. Again, the intention here is to better approximate the likely intent of the author. (I realize that CM does not define a footnote syntax, but I suspect it its CM's precedence rules that interfere with the expected footnote output.)

[wooorm]

I’m personally on the other side of this (https://github.com/commonmark/commonmark-spec/issues/653)

[theory]

@wooorm Huh. I read #653 previously, and didn't see a conflict. Is it not mainly about the use of whitespace in empty link brackets?

[wooorm]

The current rules prevent shortcuts from forming links by not allowing them if they’re followed by an empty ([]), or a valid label ([x], whether it matches or not). That leaves invalid labels, as in, whitespace-only ([ ]). #653 wants to make that rule stricter (and simpler) by not allowing whitespace-only “labels” either: if a shortcut is followed by [, it’s not a shortcut.

However, I think your idea here is to prefer shortcuts, if they could be valid. Regardless of what they’re followed with.

[theory]

Hrm. Empty brackets after a shortcut link are, in fact, the original shortcut design for Markdown itself; shortcuts without them were implemented but never documented, IIRC (but quite popular, IIRC). In fact, adding them where how I worked around this issue in my project (theory/justatheory@5e673f1).

But yes, my preference is to try to follow what the document author likely means: If the shortcut is defined, preferentially resolve it, especially if an alternative interpretation does not resolve to a shortcut reference. I believe it will then be less surprising to the author, and more closely follow what they mean.

[wooorm]

Sorry, to clarify my intent: I do not propose removing shortcuts. I’m fine with shortcuts ([w]). I’m fine with collapsed ([x][]), and with full ([y][z]) references. But I want to be less ambiguous.

Note also, that neither my proposal, nor your proposal, nor CM, resembles how references worked in Markdown.pl:

[w][n] [x][y], [z][ ]

[w]: a
[x]: b
[y]: c
[z]: d

Yields (in Markdown.pl):

<p><a href="a">w</a>[n] <a href="c">x</a>, <a href="d">z</a>[ ]</p>

Yields (CM spec in my understanding):

<p>[w][n] <a href="c">x</a>, <a href="d">z</a>[ ]</p>

Yields (CM.js):

<p>[w][n] <a href="c">x</a>, [z][ ]</p>

Yields (your proposal, I believe):

<p><a href="a">w</a>[n] <a href="b">x</a><a href="c">y</a>, <a href="d">z</a>[ ]</p>

[theory]

Yes, that seems like a fair representation. I agree that brackets with empty space shouldn't resolve to anything.

Pasting your example into Babelmark 2, it looks like commonmark.js gives slightly different results than you expect. Not sure why I don't see renderings from all the engines, though. :-(

[wooorm]

Oh didn’t know there’s a babelmark@2. Works for me. 🤷‍♂️ Maybe try a different browser? Or, maybe this is obvious but just to be sure: it groups renderings with the same output together

[vassudanagunta]

babelmark 1 (dead)

babelmark 2

babelmark 3

[theory]

Or, maybe this is obvious but just to be sure: it groups renderings with the same output together

🤦🏻‍♂️ Of course. Was not obvious to me, but is now that you say it. Easier for me to realize in bablemark 3 (thanks @vassudanagunta!). Fascinating that none of them produce either my or your suggested interpretations. Gotta love edge cases!