# 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

<!-- rumdl-disable MD054 -->

### ✅ 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 ![company logo](https://example.com/logo.png).
```

### ✅ 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).
```

<!-- rumdl-enable MD054 -->

## 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 ![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
```

### Link and image styles

- **`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

```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:

| 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

- [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)
