Skip to content

MD076 - List item spacing should be consistent

Aliases: list-item-spacing

What this rule does

Enforces consistent blank-line spacing between consecutive items in a list. Within each list, every inter-item gap must follow the same style: either all gaps have a blank line (loose) or none do (tight).

Why this matters

  • Visual consistency: Mixing tight and loose gaps in a single list looks accidental and is harder to read.
  • Rendered output: Many renderers apply extra <p> wrapping around list items that have blank lines between them. Inconsistency causes some items to render as paragraphs and others not, producing an uneven result.

Examples

Tight list (no blank lines between items)

Correct

- Item 1
- Item 2
- Item 3

Incorrect (mixed spacing)

- Item 1

- Item 2
- Item 3

Loose list (blank line between every item)

Correct

- Item 1

- Item 2

- Item 3

Incorrect (mixed spacing)

- Item 1
- Item 2

- Item 3

Ordered lists

The rule applies equally to ordered lists:

1. First

2. Second

3. Third

Configuration

[MD076]
style = "consistent"              # "consistent" (default), "loose", or "tight"
allow-loose-continuation = false  # allow blank lines around continuation paragraphs
Key Values Default
style "consistent", "loose", "tight" "consistent"
allow-loose-continuation true, false false

Style values

Value Description
"consistent" Within each list the majority style wins; on a tie, loose is preferred
"loose" Every inter-item gap must contain a blank line
"tight" No inter-item gap may contain a blank line

allow-loose-continuation

When allow-loose-continuation is true, blank lines around continuation paragraphs within a list item are permitted even in tight mode. This lets you keep tight inter-item spacing while using blank lines to visually separate multi-paragraph content within items.

Example: tight items with loose continuation

[MD076]
style = "tight"
allow-loose-continuation = true

- List item.

  Continuation paragraph that provides more detail.

- Another item.

  Its continuation paragraph.

- Simple item.
- Another simple item.

Without allow-loose-continuation, this would trigger warnings because the blank lines before/after continuation paragraphs look like loose inter-item gaps. With it enabled, only blank lines between actual item markers are checked.

Automatic fixes

This rule can automatically fix violations:

  • Missing blank lines (tight gap when loose is required): a blank line is inserted before the next list item.
  • Unexpected blank lines (loose gap when tight is required): the blank line is removed.

Fixes preserve blockquote prefixes (e.g., > characters) when list items appear inside a blockquote.

Nested lists

Nested lists are analysed independently from their parent list. A tight parent with a loose nested list (or vice versa) triggers no warning on the parent level; only the spacing at each nesting level's own items is checked.