Skip to content

MD052 - reference-links-images

Description

This rule checks that all reference-style links and images use labels that are actually defined in the document. Reference links use the format [text][label] (full) or [label][] (collapsed), and must have a corresponding [label]: URL definition. Shortcut syntax ([label]) is not checked by default because it is ambiguous — the text [example] could be a shortcut link or simply the word "example" in brackets. To include shortcut syntax, set the shortcut_syntax option to true. Brackets can be escaped with \ to avoid false positives: \[example\].

Rationale

When a reference link or image uses a label that is not defined, the link will not render correctly and will display as literal text with brackets.

Configuration

shortcut_syntax

Whether to check shortcut syntax (e.g., [label]).

  • Default: false
ignored_labels

List of labels to ignore (e.g., x for task lists).

  • Default: ["x"]

Examples

Invalid

# Document with Undefined References

This is a [full reference][undefined] link.

This is a [missing][] collapsed link.

This is an image: ![alt text][no-image]

Valid

# Document with Defined References

This is a [full reference][label] link.

This is a [collapsed][] link.

This is an image: ![alt text][image]

[label]: https://example.com/label
[collapsed]: https://example.com/collapsed
[image]: https://example.com/image.png