MD052 - Reference Links and Images
Reference links and images should use a label that is defined.
Why This Rule Exists
Reference-style links like [text][label] must have a corresponding definition.
Undefined references render as plain text instead of links.
Examples
Incorrect
Check out the [documentation][docs] for more info.
Visit [our website][site].
<!-- Missing definitions for 'docs' and 'site' -->
Correct
Check out the [documentation][docs] for more info.
Visit [our website][site].
[docs]: https://docs.example.com
[site]: https://example.com
Images
![Logo][logo]
[logo]: ./images/logo.png "Company Logo"
Configuration
[MD052]
# Labels that are never reported as undefined.
# Defaults cover task list checkboxes and GitHub-style admonitions.
ignored_labels = [" ", "x", "!note", "!tip", "!important", "!warning", "!caution"]
# Whether bare [label] shortcut references are validated. Default: false.
shortcut_syntax = false
shortcut_syntax
With the default false, only full [text][label] and collapsed [text][]
references are checked. Bare [label] text is left alone, so prose such as
- [web] Fix the sidebar is not reported as a broken link.
Set it to true to also validate shortcut references:
[MD052]
shortcut_syntax = true
Under true, [missing] is reported when no [missing]: definition exists.
When to Disable
- Documents where references are defined in included files
- Templates with programmatically injected definitions
Rule Details
- Rule ID: MD052
- Aliases: reference-links-images
- Category: Links
- Severity: Warning
- Auto-fix: No
Reference Link Syntax
<!-- Full reference -->
[Link text][label]
<!-- Collapsed reference (label matches text) -->
[Example][]
<!-- Shortcut reference -->
[Example]
<!-- Definition -->
[label]: url "Optional Title"