Skip to content

MD054 - Use consistent link and image style

Aliases: link-image-style

What this rule does

Ensures all links and images in your document use the same formatting style for better consistency and readability.

Why this matters

  • Professional appearance: Mixed link styles make documents look disorganized
  • Easier maintenance: Consistent style makes it easier to find and update links
  • Better readability: Readers can quickly recognize and understand link patterns
  • Team consistency: Everyone follows the same linking conventions

Examples

✅ Correct (all inline style)

Check out [our website](https://example.com) for more info.

See the [documentation](https://docs.example.com) for details.

View our ![company logo](https://example.com/logo.png).

✅ Correct (all reference style)

Check out [our website][site] for more info.

See the [documentation][docs] for details.

View our ![company logo][logo].

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

❌ Incorrect (mixed styles)

Check out [our website](https://example.com) for more info.

See the [documentation][docs] for details.

View our <https://example.com/contact> page.

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

🔧 Fixed

Check out [our website](https://example.com) for more info.

See the [documentation](https://docs.example.com) for details.

View our [contact page](https://example.com/contact).

Configuration

Configure which link and image styles are allowed in your documents. By default, all styles are allowed. Set a style to false to disallow it.

[MD054]
autolink = true             # Allow <https://example.com>
inline = true               # Allow [text](url) and ![alt](url)
full = true                 # Allow [text][ref] with separate [ref]: url definition
collapsed = true            # Allow [text][] with separate [text]: url definition
shortcut = true             # Allow [text] with separate [text]: url definition
url-inline = true           # Allow [https://example.com](https://example.com)
preferred-style = "auto"    # Target style used by --fix when rewriting disallowed links
  • autolink: <https://example.com> - Bare URLs in angle brackets
  • inline: [text](url) and ![alt](url) - Direct inline links and images
  • full: [text][ref] - Full reference with separate definition [ref]: url
  • collapsed: [text][] - Collapsed reference (label matches definition)
  • shortcut: [text] - Shortcut reference (just label, definition inferred)
  • url-inline: [https://example.com](https://example.com) - URL as both text and destination

preferred-style

Controls which style --fix rewrites disallowed links and images into. When several styles are allowed, this picks the conversion target.

Accepts either a single style name or a list of style names in priority order. When a list is given, each entry is tried in turn and the first one that's both allowed by the config and reachable from the source style wins. The special value auto may appear anywhere in the list and expands to the source-aware default ordering — useful as a wildcard fallback after explicit preferences.

Available values

  • "auto" (default) - Pick the highest-priority allowed style that's also a well-defined target for the source. Reference-style sources collapse back to inline; inline sources expand to full; url-inline sources prefer autolink (when reachable) over reference forms; autolinks become url-inline (or inline).
  • "full" - Always rewrite to [text][label], generating a fresh [label]: url definition when needed and reusing any existing definition with the same URL.
  • "collapsed" - Rewrite to [text][]. Only used when the existing reference label already matches the link text (otherwise the warning is left without an auto-fix).
  • "shortcut" - Rewrite to [text], with the same matching constraint as collapsed.
  • "inline" - Rewrite to [text](url) for non-URL link text, splicing the URL and title back from the matching reference definition.
  • "autolink" - Rewrite to <url>. Only valid when the link text equals the URL and the URL is autolink-safe (a real URI or email).
  • "url-inline" - Rewrite to [url](url). Used for autolinks when inline is disallowed.

Scalar form

[MD054]
preferred-style = "full"

List form (priority order)

Try autolink first; fall back to full for URLs that aren't autolink-safe (relative paths, anchors, ...) so every disallowed link still gets fixed:

[MD054]
preferred-style = ["autolink", "full"]

Use auto as a wildcard fallback. Below, the rule prefers autolink and falls through to the source-aware default ordering otherwise:

[MD054]
preferred-style = ["autolink", "auto"]

Common configurations

Only allow inline links:

[MD054]
autolink = false
inline = true
full = false
collapsed = false
shortcut = false
url-inline = false

Only allow reference-style links:

[MD054]
autolink = false
inline = false
full = true
collapsed = true
shortcut = true
url-inline = false

Prefer autolinks for bare URLs:

[MD054]
autolink = true
inline = true
full = true
collapsed = true
shortcut = true
url-inline = false  # Disallow [url](url), prefer <url> instead

Force every link to reference style on fix:

[MD054]
autolink = false
inline = false
url-inline = false
full = true
collapsed = true
shortcut = true
preferred-style = "full"

Automatic fixes

When --fix is run, MD054 rewrites disallowed links and images into an allowed style. The supported conversions are:

From To
inline full, collapsed, shortcut, autolink
url-inline full, collapsed, shortcut, autolink, inline
autolink inline, url-inline, full
full inline, collapsed, shortcut
collapsed inline, full, shortcut
shortcut inline, full, collapsed

Reference-label generation for full targets:

  • Labels are slugified from the link text (lowercase, runs of non-alphanumeric collapsed to -); when text is empty the URL is used.
  • Existing reference definitions are reused when the URL already has one — no duplicate definition is emitted.
  • Collisions are disambiguated with -2, -3, ... suffixes.

A few conversions are intentionally out of scope and the warning is left without a fix:

  • inline → autolink when the link text doesn't equal the URL (lossy conversion).
  • inline → autolink when the URL isn't a valid autolink (no scheme, contains spaces, etc.).
  • full → collapsed/shortcut when the existing reference label doesn't match the link text (would require renaming the reference definition).
  • Image → autolink (images can't be autolinks).

Learn more