A markdownlint companion rule to MD052 that flags shortcut reference links and can auto-convert them to collapsed form.

Markdown supports three forms of reference links:

An undefined reference is a reference link with no matching definition. MD052 reports undefined references, but it ignores shortcut syntax by default because bracketed text can be ambiguous.

Converting shortcuts to collapsed form lets MD052 catch missing definitions. If MD052 configuration alone suffices, see MD052 vs this rule.

• A defined shortcut is [label] with a matching link definition in the same document.

• Defined shortcuts are flagged for both single- and multi-word labels (for example, [Custom Rules]).

• Undefined shortcuts are flagged by default. Set check_undefined to false to only flag refs with a matching definition.

npm install --save-dev markdownlint-rule-no-shortcut-ref-link

Or from GitHub, pinned to a tag:

npm install --save-dev github:chalin/markdownlint-rule-no-shortcut-ref-link#v0.4.0

In .markdownlint-cli2.yaml:

customRules:
  - markdownlint-rule-no-shortcut-ref-link

In .markdownlint.yaml:

no-shortcut-ref-link: true

To only flag shortcut refs that have a definition (and ignore undefined ones), set check_undefined: false:

no-shortcut-ref-link:
  check_undefined: false

Use ignore_pattern to skip labels that match a regular expression. For example, to ignore footnote-style numeric references like [1]:

no-shortcut-ref-link:
  ignore_pattern: '^\d+$'

The following are always skipped regardless of configuration to avoid common false positives:

• GitHub alert syntax: [!NOTE], [!WARNING], etc.
• Footnote references: [^1], [^note], etc.
• Wiki links (Obsidian/Foam style): [[page]], [[page|alias]], etc.
• Labels embedded in identifiers: e.g. otel.[name].enabled, where both the character before [ and after ] are alphanumeric or ..
• Unresolved inline links: e.g. [text]({{...}}), where ] is immediately followed by (. This covers template URLs that micromark cannot parse.
• Content inside raw-content HTML blocks (<script>, <style>, <pre>, <textarea>) so JS/CSS/textarea/pre bracket syntax is not touched. Shortcut refs inside other HTML blocks (e.g. <div>) are still flagged and fixed.
• Bracketed text inside inline HTML <code>...</code> tags.

Run your linter with the --fix flag to auto-convert shortcut references:

npx --no -- markdownlint-cli2 --fix '**/*.md'

Use MD052 (reference-links-images) when:

• You only need undefined-reference checks.
• shortcut_syntax: true with configured ignored_labels covers your needs.

Example config:

reference-links-images:
  shortcut_syntax: true
  ignored_labels:
    # Ignore GitHub alert syntax
    - '!note'
    - '!warning'
    - ...
    # Ignore footnote-style numeric references
    - '1'
    - '2'
    - ...

Use this rule (no-shortcut-ref-link) as a companion when:

• You want to standardize on collapsed syntax ([label][]).
• You want auto-fix from shortcut to collapsed form.
• MD052 configuration alone is noisy or hard to tune for your content.

Licensed under Apache-2.0. Copyright 2026-present @chalin and contributors.