no-unused-definitions

Disallow unused definitions.

Background

In Markdown, you can define reference-style links, images, and footnotes using definitions that appear elsewhere in the document. These definitions consist of an identifier followed by a URL, image source, or footnote content. However, when definitions are created but never referenced in the document, they become unused and potentially confusing.

Unused definitions can cause several issues:

They add unnecessary clutter to the document.
They might indicate broken references or content that was intended to be included.
They can mislead readers who might assume the definitions are being used somewhere.

Cleaning up unused definitions helps maintain a more organized and intentional document structure.

Rule Details

Important

The footnotes are only supported when using language mode markdown/gfm.

This rule warns about unused reference definitions in Markdown documents. It detects definition entries (e.g., [reference-id]: http://example.com) that aren't used by any links, images, or footnotes in the document, and reports them as violations. Please note that this rule doesn't report definition-style comments (e.g., [//]: # (This is a comment)) by default.

Examples of incorrect code:

<!-- eslint markdown/no-unused-definitions: "error" -->

<!-- definition -->

[mercury]: https://example.com/mercury/

[venus]: https://example.com/venus.jpg

<!-- footnote definition -->

[^mercury]: Hello, Mercury!

Examples of correct code:

<!-- eslint markdown/no-unused-definitions: "error" -->

<!-- definition -->

[Mercury][mercury]

[mercury]: https://example.com/mercury/

![Venus Image][venus]

[venus]: https://example.com/venus.jpg

<!-- footnote definition -->

Mercury[^mercury]

[^mercury]: Hello, Mercury!

<!-- definition-style comment -->

[//]: # (This is a comment 1)
[//]: <> (This is a comment 2)

Options

allowDefinitions: Array<string> - when specified, unused definitions are allowed if they match one of the identifiers in this array. This is useful for ignoring definitions that are intentionally unused. (default: ["//"])

Examples of correct code when configured as "no-unused-definitions": ["error", { allowDefinitions: ["mercury"] }]:
```


[mercury]: https://example.com/mercury/
[mercury]: https://example.com/venus/
```
allowFootnoteDefinitions: Array<string> - when specified, unused footnote definitions are allowed if they match one of the identifiers in this array. This is useful for ignoring footnote definitions that are intentionally unused. (default: [])

Examples of correct code when configured as "no-unused-definitions": ["error", { allowFootnoteDefinitions: ["mercury"] }]:
```


[^mercury]: Hello, Mercury!
[^mercury]: Hello, Venus!
```

When Not to Use It

You might want to disable this rule if:

You're maintaining a document with intentionally defined but temporarily unused references.
You're using reference definitions as a form of comment or placeholder for future content.

Prior Art

MD053 - Link and image reference definitions should be needed
remark-lint-no-unused-definitions

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!