Skip to content

MD077 - List continuation content indentation

Aliases: list-continuation-indent

What this rule does

Checks that content after a blank line inside a list item is indented to the item's content column (the W+N rule from the CommonMark spec). Under the MkDocs flavor, a minimum of 4 spaces is enforced to satisfy Python-Markdown's stricter requirement.

Why this matters

  • Rendering correctness: Insufficient indentation after a blank line causes the content to "escape" the list item. Most renderers will close the list and render the content as a separate paragraph, which is usually not what the author intended.
  • MkDocs compatibility: Python-Markdown (used by MkDocs) requires at least 4 spaces of indentation for ordered list continuation, even when the marker is only 3 characters wide (e.g., 1.). CommonMark accepts 3 spaces in this case, so documents can silently break when deployed to MkDocs.

Examples

Unordered list

Correct

- Item

  Continuation paragraph (2-space indent matches `- ` marker width).

Incorrect

- Item

 Continuation paragraph (1-space indent — not enough for `- ` marker).

Note: Content at 0 indent after a blank line starts a new paragraph and is not flagged. MD077 only flags content with partial indentation (above the marker column but below the content column), which signals an indentation mistake rather than an intentional new paragraph.

Ordered list (CommonMark)

Correct

1. Item

   Continuation paragraph (3-space indent matches `1. ` marker width).

Incorrect

1. Item

  Continuation paragraph (2-space indent — not enough for `1. ` marker).

Ordered list (MkDocs flavor)

Correct

1. Item

    Continuation paragraph (4-space indent required by Python-Markdown).

Incorrect

1. Item

   Continuation paragraph (3 spaces — valid CommonMark but breaks in MkDocs).

Multi-digit markers

10. Item

    Continuation paragraph (4-space indent matches `10. ` marker width).

Flavor-aware behavior

Flavor Required indent
Standard content column (W+N from marker width)
MkDocs max(content column, 4)

Under MkDocs flavor, both ordered and unordered list items require at least 4 spaces of continuation indent to ensure Python-Markdown compatibility.

Code blocks inside list items

Fenced code block delimiters (``` and ~~~) are checked for indentation just like prose continuation content. The content between the fences is not checked — only the opener and closer lines matter for determining whether the code block belongs to the list item.

1. Item

    ```toml        ← checked (fence opener)
    key = "value"  ← not checked (code content)
    ```             ← checked (fence closer)

Note: The automatic fix adjusts fence delimiter indentation but does not modify code block content indentation. After applying the fix you may want to manually re-indent the code content for visual consistency.

Lazy continuation (no blank line)

This rule does not flag lazy continuation — content that directly follows a list item without an intervening blank line:

- Item
continuation (lazy — not flagged by MD077)

Lazy continuation is valid CommonMark and handled by the parser regardless of indentation. MD077 only checks content after a blank line.

Automatic fixes

This rule can automatically fix violations by adjusting the leading whitespace to the required indent level.

rumdl check --fix document.md