If there are several matching definitions, the first one takes precedence:
[foo]
[foo]: first
[foo]: second
<p><a href="first">foo</a></p>
What defines “first”? Is this underdefined?
For example, what if I have this content:
this is my first paragraph, with a [link].
[link]: first
this is my second paragraph, with another [link].
[link]: second
The CommonMark dingus suggests that the appropriate translation makes both links first, but I feel like this is unclear from the documentation, as “first” might suggest “first after”, where the first paragraph links to first and the second links to second.
The spec should also consider now that there may be implicit link targets in the future. Probably, an explicit target overwrites an implicit one.
# Link Target
Here’s a [link][Link Target].
[Link Target]: #first
[Link Target]: #second
Here it is again: [link][Link Target].
[Link Target]: #third
And a final time, [link][Link Target].
My reasoning for preferring the first match (meaning: the first definition encountered in the document) was as follows. It’s often handy to have a file with a big list of standard reference definitions, refs.md, which you can append to anything:
cmark myfile.md refs.md
That way you don’t have to repeat the reference definitions in everything you write. But with this workflow you’d certainly want a definition in myfile.md to override one in refs.md. Preferring the first definition achieves this.
I don’t know how many people are using that workflow, but couldn’t they just use the reverse order?
cmark refs.md myfile.md
I thought one of the design goals of Commonmark was to reflect existing Markdown implementations. They are almost interoperable in choosing the last definition. Only newer implementations which were build for CM instead of MD (i.e. the reference implementation, cheapskate and markdown-it) choose the first, and Discount strangely the second.
Maybe the reverse workflow could be used. But it might mess things up if, e.g., your converter is trained to parse an initial YAML metadata section.
I did notice that most current implementations prefer the last definition, but I assume that existing documents don’t depend on this, as duplicated references are nearly always just a mistake. So it seemed worth changing this if there is an advantage to doing so.
The BabelMark disagreement is kinda funny; it seems like CommonMark might have gone against accepted practice here.
I’m not even posting this as a proposal of the alternative (imo more sensible) approach that would handle links with the nearest succeeding link definition. I just thought the current spec was unclear and could potentially be read that way
