MD053 - Remove unused link definitions¶

Aliases: link-image-reference-definitions

What this rule does¶

Finds link and image reference definitions that aren't used anywhere in your document and removes them to keep your content clean.

Why this matters¶

Reduces clutter: Unused definitions make documents harder to maintain
Prevents confusion: Developers might wonder why certain definitions exist
Improves readability: Less scrolling through unused references at the bottom of files
Easier maintenance: Fewer references to check when updating links

Examples¶

✅ Correct¶

# My Document

Check out [our website][site] and view the [documentation][docs].

See our ![company logo][logo] for branding guidelines.

[site]: https://example.com
[docs]: https://docs.example.com
[logo]: /images/logo.png

❌ Incorrect¶

# My Document

Check out [our website](https://example.com) directly.

[site]: https://example.com
[docs]: https://docs.example.com
[unused]: https://old.example.com
[legacy]: https://legacy.example.com

🔧 Fixed¶

# My Document

Check out [our website](https://example.com) directly.

Configuration¶

[MD053]
ignored-definitions = []  # List of reference names to keep even if unused

Example with ignored definitions¶

[MD053]
ignored-definitions = ["todo", "draft", "template"]

This keeps reference definitions with names like "todo", "draft", or "template" even if they're not currently used.

Comment-Style References¶

rumdl automatically recognizes and ignores common community patterns for adding comments using reference-style syntax. These patterns are not part of any official Markdown specification (CommonMark, GFM), but are widely used across 23+ Markdown implementations.

Recognized Comment Patterns¶

The following patterns are automatically ignored and won't be flagged as unused:

[//]: # (This is a comment - most popular pattern)
[comment]: # (This is a semantic comment)
[note]: # (This is a note for documentation)
[todo]: # (Add more examples here)
[fixme]: # (This needs to be fixed)
[hack]: # (Temporary workaround)

Any reference definition with just # as the URL is also treated as a comment:

[anything]: # (This will be treated as a comment)
[ref]: # "Also a comment"

Why These Work¶

These patterns exploit valid Markdown link reference syntax:

The label (e.g., [//]) is technically valid
The # is a valid URL (just a fragment/anchor)
Since the reference is never used, it doesn't render

When to Use¶

Use HTML comments for standard commenting:

<!-- This is the recommended way to add comments -->

Use reference-style comments when:

Your documentation tool strips HTML comments
You prefer a less HTML-like syntax
You're following project conventions that use this pattern
You need comments that won't appear in page source

Real vs. Comment References¶

rumdl distinguishes between comment patterns and real references:

[//]: # (This is ignored - it's a comment)
[real-link]: https://example.com  <!-- This WILL be flagged if unused -->

Only the real reference definition will trigger MD053 if it's not used in the document.

Automatic fixes¶

This rule can automatically fix issues by:

Removing entire lines containing unused reference definitions
Preserving any definitions listed in ignored_definitions
Cleaning up extra blank lines left behind