MD052 - Fix broken reference links and images

December 9, 2025 · View on GitHub

Aliases: reference-links-images

What this rule does

Checks that all reference-style links and images point to definitions that actually exist in your document.

Why this matters

  • Prevents broken links: Readers can't follow links that don't have destinations
  • Avoids confusion: Missing references leave readers wondering where links should go
  • Maintains trust: Broken links make your documentation appear unmaintained
  • Ensures completeness: All referenced content is properly defined

Examples

✅ Correct

This is a [reference link][example] and here's an [image reference][pic].

You can also use [numbered references][1].

[example]: https://example.com
[pic]: /images/photo.jpg
[1]: https://docs.example.com

❌ Incorrect

This is a [broken link][missing] and an [undefined image][nopic].

Here's a [shortcut reference] with no definition.

[other]: https://example.com

🔧 Fixed

This is a [broken link][missing] and an [undefined image][nopic].

Here's a [shortcut reference] with no definition.

[missing]: https://example.com/page
[nopic]: /images/default.jpg
[shortcut reference]: https://example.com/shortcut
[other]: https://example.com

Configuration

OptionTypeDefaultDescription
shortcut-syntaxbooleanfalseCheck shortcut reference syntax [text]
ignorestring[][]Reference names to ignore (case-insensitive)

By default, shortcut reference syntax ([text] without a label) is not checked because it can produce false positives when the text resembles other markdown constructs.

[MD052]
shortcut-syntax = true  # Enable checking of shortcut references

Ignoring specific references

Use the ignore option to specify reference names that should not be flagged as undefined. This is useful when you have references that are intentionally undefined (e.g., Rust documentation where [Vec] links are resolved by rustdoc).

[MD052]
ignore = ["Vec", "HashMap", "Option", "Result"]

Matching is case-insensitive since reference IDs are normalized to lowercase during parsing.

Automatic fixes

This rule cannot automatically fix issues because it can't know what URL you intended for missing references. You must manually:

  1. Add the missing reference definition at the bottom of your document
  2. Or change the reference to use an existing definition
  3. Or convert to an inline link if a reference isn't needed

Learn more