Skip to content

MD054.md

Latest commit

 

History

History
94 lines (66 loc) · 2.85 KB

MD054.md

File metadata and controls

94 lines (66 loc) · 2.85 KB

MD054 - Link and image style

Description

MD054 checks for consistent use of link and image styles. Different styles include:

  • Autolinks: <https://example.com>
  • Inline: [text](url) and ![alt](url)
  • Full reference: [text][ref] and ![alt][ref] with [ref]: url
  • Collapsed reference: [text][] and ![alt][] with [text]: url
  • Shortcut reference: [text] and ![alt] with [text]: url
  • URL inline: [https://example.com](https://example.com) (inline where text matches URL)

Configuration

This rule accepts an object with the following properties:

  • autolink - Allow autolinks (default: true)
  • inline - Allow inline links and images (default: true)
  • full - Allow full reference links and images (default: true)
  • collapsed - Allow collapsed reference links and images (default: true)
  • shortcut - Allow shortcut reference links and images (default: true)
  • url_inline - Allow inline links where text matches URL (default: true)

Example Configuration

[linters.settings.link-image-style]
autolink = false     # Disallow <https://example.com>
inline = true        # Allow [text](url) and ![alt](url)
full = true          # Allow [text][ref] and ![alt][ref]
collapsed = true     # Allow [text][] and ![alt][]
shortcut = true      # Allow [text] and ![alt]
url_inline = false   # Disallow [https://example.com](https://example.com)

Examples

❌ Invalid (when autolink = false)

Visit <https://example.com> for more information.

✅ Valid (when autolink = false, but inline = true)

Visit [our website](https://example.com) for more information.

❌ Invalid (when inline = false)

Check out [this link](https://example.com).
![Image description](https://example.com/image.jpg)

✅ Valid (when inline = false, but full = true)

Check out [this link][example].
![Image description][example-image]

[example]: https://example.com
[example-image]: https://example.com/image.jpg

❌ Invalid (when url_inline = false)

Visit [https://example.com](https://example.com).

✅ Valid (when url_inline = false)

Visit [our website](https://example.com).

Rationale

Different projects may prefer different link and image styles for consistency and readability. Some considerations:

  • Autolinks are simple but don't allow custom text
  • Inline links are readable but can make long URLs unwieldy
  • Reference links keep URLs separate from text, improving readability
  • URL inline links are redundant and add visual clutter

This rule allows you to enforce a consistent style across your documentation.

References