# 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)
```markdown
Check out [our website](https://example.com) for more info.
See the [documentation](https://docs.example.com) for details.
View our .
```
### ✅ Correct (all reference style)
```markdown
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)
```markdown
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
```markdown
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.
```toml
[MD054]
autolink = true # Allow <https://example.com>
inline = true # Allow [text](url) and 
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
```
### Link and image styles
- **`autolink`**: `<https://example.com>` - Bare URLs in angle brackets
- **`inline`**: `[text](url)` and `` - 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
```toml
[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:
```toml
[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:
```toml
[MD054]
preferred-style = ["autolink", "auto"]
```
### Common configurations
**Only allow inline links:**
```toml
[MD054]
autolink = false
inline = true
full = false
collapsed = false
shortcut = false
url-inline = false
```
**Only allow reference-style links:**
```toml
[MD054]
autolink = false
inline = false
full = true
collapsed = true
shortcut = true
url-inline = false
```
**Prefer autolinks for bare URLs:**
```toml
[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:**
```toml
[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:
| `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
- [Markdown Guide: Links](https://www.markdownguide.org/basic-syntax/#links)
- [CommonMark: Links](https://spec.commonmark.org/0.31.2/#links)
## Related rules
- [MD042 - Ensure links have content](md042.md)
- [MD034 - Format bare URLs properly](md034.md)
- [MD052 - Fix broken reference links](md052.md)