Skip to content

Rule - MD005#

Property Value
Aliases md005, list-indent
Autofix Available Yes
Enabled By Default Yes

Summary#

List items at the same nesting level must share consistent indentation.

Reasoning#

Readability#

Inconsistent indentation in lists does not affect parsing engines, but it makes source documents harder for humans to scan. Enforcing consistent indentation ensures list structure is visually clear and predictable.

Examples#

Failure Scenarios#

This rule triggers when list items at the same level have inconsistent indentation, such as an unordered list item that is indented more than its siblings.

* Item 1
* Item 2
 * Misaligned item

Explanation: The third item is indented by one space more than the first two items. This violates the rule because all items at the same nesting level should start at the same horizontal position.

Unlike the previous unordered list example, this ordered list fails because the second item's indentation does not align with the first item's start or delimiter.

1. Item 1
 2. Item 2

Explanation: The first item starts at column 1. The second item starts at column 2, which misaligns both the text content and the delimiter (.) relative to the first item. This violates the rule's requirement for consistent indentation or alignment.

Unlike the previous single-list examples, this case mixes left-aligned and right-aligned sublists under different parents, violating the rule's requirement for consistent alignment across the entire list structure.

1. Item 1
   1. Item 1a
   10. Item 1b
2. Item 2
    1. Item 2a
   10. Item 2b

Explanation: The sublist under Item 1 is left-aligned (delimiter 1. and 10. align), while the sublist under Item 2 is right-aligned (1. is indented more than 10.). The rule enforces consistent alignment across the entire list structure, so this mixture triggers the failure.

Unlike the previous examples that show excess indentation, this case shows a nested item that is insufficiently indented relative to its sibling at the same nesting level.

* Item 1
 * Item 1a
* Item 2
  * Item 2a

Explanation: Both Item 1a and Item 2a are nested at the same logical depth under their respective parent items. However, Item 1a is indented by only 1 space while Item 2a is indented by 2 spaces. Because both children occupy the same nesting level, the rule requires them to share a consistent indentation width. The mismatch triggers the failure.

Correct Scenarios#

This rule does not trigger when all unordered list items at the same level share consistent indentation, including proper indentation for nested sublists.

* Item 1
  * Item 1a
* Item 2
  * Item 2a

Explanation: All top-level items (Item 1, Item 2) start at column 0. All nested items (Item 1a, Item 2a) are indented consistently by 2 spaces. This satisfies the rule's requirement for uniform indentation at each nesting level.

Unlike unordered lists, this ordered list example shows left-aligned items where the delimiter characters are vertically aligned.

1. Item
10. Item
100. Item

Explanation: The delimiter characters (1., 10., 100.) are left-aligned at column 0. This is a valid format supported by the rule for ordered lists.

Unlike the previous left-aligned example, this ordered list shows right-aligned items where the end of the delimiter characters is vertically aligned.

  1. Item
 10. Item
100. Item

Explanation: The delimiter characters are right-aligned, meaning the periods (.) are in the same column. This is also a valid format supported by the rule for ordered lists.

Unlike the previous right-aligned example, this is an edge case where the indentation is so large that Markdown parsers treat the content as an indented code block rather than an ordered list, so the rule does not apply.

    1. Item
   10. Item
  100. Item
 1000. Item
10000. Item

Explanation: The first item is indented by 4 spaces, which Markdown parsers interpret as an indented code block rather than an ordered list. Since the construct is not a list, this rule's list-indentation criteria do not apply.

Fix Description#

The autofix collects all list items within a contiguous list block. For ordered lists, it determines whether right-alignment is intended. If so, it aligns the delimiters to the right. Otherwise, it aligns all items at the same nesting level to start at the same column as the first item. This ensures consistent indentation across the entire list structure.

Configuration#

Prefixes
plugins.md005.
plugins.list-indent.
Value Name Type Default Description
enabled boolean True Determines if this rule is active.

Origination of Rule#

This rule is largely inspired by the MarkdownLint rule MD005.

Differences From MarkdownLint Rule#

The original rule did not consider alignment consistency across sublists within a parent list. As such, it was possible to have a list containing sublists that mixed left-aligned lists with right-aligned lists. This rule resets its notion of the proper alignment for Ordered Lists when the base Ordered List is closed.