Rule - MD053#

Property	Value
Aliases	`md053`, `link-image-reference-definitions`
Autofix Available	No
Enabled By Default	Yes

Summary#

Link and image reference definitions should be needed by at least one link or image in the document, and each label should be defined only once.

Reasoning#

Readability#

Link reference definitions allow documents to keep links organized in one place. Unused definitions add clutter that a reader has to mentally filter out.

Consistency#

When multiple definitions share the same label (case-insensitive), it becomes ambiguous which URL is intended. Enforcing a single definition per label keeps the meaning of a reference consistent throughout the document.

Note: Labels are compared after Unicode case-folding, stripping leading/trailing whitespace, and collapsing internal whitespace. For example, some-link, Some-Link, and some link are treated as identical.

Examples#

Failure Scenarios#

This rule triggers when a link reference definition is defined but not used anywhere in the document.

Go to [this link][some-link].

[some-link]: /url
[some-other-link]: /url

Explanation: The definition [some-other-link] is present but never referenced by any link or image in the document. This violates the rule because link reference definitions should be needed.

Unlike the previous example, this case uses a link reference label that is defined multiple times.

Go to [this link][some-link].

[some-link]: /url
[Some-Link]: /other-url

Explanation: The label some-link is defined twice — once as [some-link] and once as [Some-Link]. Because labels are compared case-insensitively, these are the same label. Per GFM, the first definition takes precedence, so the second definition ([Some-Link]) is never used and is redundant, which violates the rule.

Unlike the previous example, this case leaves an image reference definition unused.

Here is a logo: ![logo][logo-label].

[logo-label]: /logo.png
[unused-image]: /other.png

Explanation: The definition [unused-image] is never referenced by any image or link. The rule applies to both link and image reference definitions, so this unused image definition violates the rule.

Unlike the previous examples, this case leaves an image reference definition duplicated with a different label casing.

Here is a logo: ![logo][logo-label].

[logo-label]: /logo.png
[Logo-Label]: /other.png

Explanation: The label logo-label is defined twice — once as [logo-label] and once as [Logo-Label]. Because labels are compared case-insensitively, these are the same label. Per GFM, the first definition takes precedence, so the second definition ([Logo-Label]) is never used and is redundant, which violates the rule.

Correct Scenarios#

This rule does not trigger when all link reference definitions are used and have unique labels.

Go to [this link][some-link].
Show ![this image][some-other-link].

[some-link]: /url
[some-other-link]: /image-url

Explanation: Both [some-link] and [some-other-link] are defined exactly once and referenced in the document. This satisfies the rule requirement that definitions must be needed and unique.

Unlike the previous example, this case uses link reference definitions with labels that are configured to be ignored, effectively acting as comments.

[//]: /u (This behaves like a comment)

Explanation: The definition [//] is present but never referenced by any link or image. However, because // is included in the ignored-definitions configuration item (default value "//"), this definition is excluded from triggering the rule. This satisfies the rule by being an explicitly allowed exception.

Unlike the previous examples, this case uses a label that is referenced with different casing, which is valid under GFM case-insensitive matching.

Go to [this link][some-link].

[Some-Link]: /url

Explanation: The label Some-Link in the definition matches the reference [some-link] case-insensitively (per GFM), so the definition is considered used. Because the definition is used and the label is unique (no second definition exists), the rule does not trigger.

Fix Description#

The reason for not being able to auto-fix this rule is certainty. Removing unused definitions is generally safe, but determining whether a duplicate definition should be removed or merged requires understanding the author's intent. Additionally, some definitions may be intentionally ignored (via ignored-definitions), and auto-removal could delete definitions that the user considers valid comments or placeholders. Therefore, manual review is required to ensure no intended definitions are incorrectly removed.

Configuration#

Prefixes
`plugins.md053.`
`plugins.link-image-reference-definitions.`

Value Name	Type	Default	Description
`enabled`	`boolean`	`True`	Whether the Rule Plugin is enabled.
`ignored-definitions`	`str`	`"//"`	Comma-separated list of link texts that do not trigger this rule.

Origination of Rule#

This rule is largely inspired by the MarkdownLint rule MD053.