Shortcut Link Questions

Howdy. I was perusing the spec on shortcut reference link, and was a little surprised by example 567. The example:


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

And the output:

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

What I would have expected:

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

I get that the syntax itself is inherently ambiguous, so you have to make a rule, but ISTM that the existence of the [foo] reference with an actual lookup would trump the attempt to resolve [bar],which has no reference, but [baz] does. As a writer, it would think that a [xxx] syntax would preferentially resolve for links that actually exist in the reference, as opposed that don’t. Am I missing something here?


Well, I can only speculate because I am not an author of the specification, but I think the current behavior is very reasonable.

Consider any Markdown syntax construction and write it with some syntax error. Given how Markdown works, it is still perfectly valid document, but the given syntax construction is just seen as a verbatim text. (That is, unless it is broken in a way which makes it valid as a different syntax construction.)

I argue it is good fallback behavior also for links, just for the sake of consistency with that general principle.

Additionally, I argue that for links it may be even twice as important: If broken/highly ambiguous links are still rendered as links, but possibly with an unintended link location, it makes the error harder to detect in the rendered HTML. In contrast, if it is rendered as a verbatim text, it is easier to spot in the rendered document even without studying the source of the generated HTML or clicking the link to detect it leads to somewhere else than intended.

Agreed on all counts, except that this example is not ambiguous. The link references resolve the ambiguities in that they define which bracketed expressions are links and which are not.

Example 561 is perhaps a simpler example of the same issue:


[foo]: /url1

[bar]: /url2


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

This is because the spec says “Full and compact references take precedence over shortcut references". But the author, who took the time to disambiguate the references by including them both in the link reference, may find it confusing, expecting, instead:

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

I get that the parser needs to determine precedence, and I certainly wouldn’t expect anything different if [foo] wasn’t referenced in the link reference, e.g.,


[baz]: /url1

[bar]: /url2

But when I as the author have explicitly defined the labels in the references, as in example 561, I would think that would take precedence over the parer’s idea of precedence. IOW, the references should take precedence over the order of brackets in the text, because they’re explicit, and demonstrate the author’s intent.

1 Like

But when I as the author have explicitly defined the labels in the references, as in example 561, I would think that would take precedence over the parer’s idea of precedence.

I’m pretty sympathetic to this way of thinking. One could imagine changing things so that shortcut references take preference over full and compact ones when a link is defined.

It has been a while since I thought about this, so I can’t now recall what considerations led to the other decision. Very likely, it was precedent in existing Markdown implementations:[foo][bar] [foo]%3A+url1 [bar]%3A+url2


Yeah, I get that this is a pretty rare pattern for links (after all, it’s not particularly legible). But where it’s really chapping my hide is with the use of footnotes:

Visit [Foo][^1].

  [^1]: But not really[Foo][^1]. ++[Foo] ++[^1]%3A+But+not+really

I had been used to the Multimarkdown/Markdown Extra behavior, where the footnote is recognized, but the others are kind of all over the place. See, for example, markdown-it with footnotes enabled.

I realize footnotes are not part of the CM spec, but I think it’s this precedence issue that leads to the inconsistency; at least, that’s what the author of goldmark suggests.

Yes, I see how this might make it harder to add a footnote
extension. Well, maybe you should submit an issue to
commonmark-spec, and I’ll think more about it.

1 Like

Done, thanks for the thoughtful discussion.

1 Like