[GH-ISSUE #390] Emit a warning for duplicate link labels #326

New issue

Closed

opened 2026-03-03 01:25:44 +03:00 by kerem · 0 comments

kerem commented

2026-03-03 01:25:44 +03:00

Owner

Originally created by @rcdailey on GitHub (Apr 23, 2021).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/390

I am reviewing the link label documentation in the CommonMark spec, and it says:

If there are multiple matching reference link definitions, the one that comes first in the document is used. (It is desirable in such cases to emit a warning.)

An example of this situation is here:

[mylink]: http://domain1.com

This paragraph refers to [mylink].

[mylink]: http://domain2.com

In the above markdown, the paragraph using the link by label will point to http://domain1.com. It's quite possible the user did not intend to duplicate the link label, mylink, twice. A warning should be issued. Both link definitions should be flagged and the warning should instruct the user to rename one of the flagged/underlined link definition labels. An example of the solution to the above violation is below:

[mylink]: http://domain1.com

This paragraph refers to [mylink2].

[mylink2]: http://domain2.com

Above, I renamed the bottom link definition's label from mylink to mylink2, and updated the paragraph to point to it.

In some cases, no warning might be desired here, so like most of the other markdown lint rules, there should be a corresponding JSON configuration to silence this warning. Whatever that looks like, I leave up to whoever implements this.

Originally created by @rcdailey on GitHub (Apr 23, 2021). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/390 I am reviewing the [link label documentation](https://spec.commonmark.org/0.29/#link-label) in the CommonMark spec, and it says: > If there are multiple matching reference link definitions, the one that comes first in the document is used. (It is desirable in such cases to emit a warning.) An example of this situation is here: ```md [mylink]: http://domain1.com This paragraph refers to [mylink]. [mylink]: http://domain2.com ``` In the above markdown, the paragraph using the link by label will point to `http://domain1.com`. It's quite possible the user did *not* intend to duplicate the link label, `mylink`, twice. A warning should be issued. Both link definitions should be flagged and the warning should instruct the user to rename one of the flagged/underlined link definition labels. An example of the solution to the above violation is below: ```md [mylink]: http://domain1.com This paragraph refers to [mylink2]. [mylink2]: http://domain2.com ``` Above, I renamed the bottom link definition's label from `mylink` to `mylink2`, and updated the paragraph to point to it. In some cases, no warning might be desired here, so like most of the other markdown lint rules, there should be a corresponding JSON configuration to silence this warning. Whatever that looks like, I leave up to whoever implements this.