Skip to content

MD007 - Keep list indentation consistent

Aliases: ul-indent

What this rule does

Ensures nested list items are indented with exactly 2 spaces per level for consistent formatting.

Why this matters

  • Readability: Consistent indentation makes nested lists easy to scan and understand
  • Professional appearance: Well-formatted lists look polished and organized
  • Tool compatibility: Many Markdown tools expect 2-space indentation for proper rendering
  • Team consistency: Standard indentation prevents formatting conflicts in shared documents

Examples

✅ Correct

* Chapter 1
  * Section 1.1
    * Subsection 1.1.1
    * Subsection 1.1.2
  * Section 1.2
* Chapter 2
  * Section 2.1

❌ Incorrect

* Chapter 1
   * Section 1.1 (3 spaces - too many!)
      * Subsection 1.1.1 (6 spaces)
 * Section 1.2 (1 space - too few!)
* Chapter 2
    * Section 2.1 (4 spaces - inconsistent)

🔧 Fixed

* Chapter 1
  * Section 1.1
    * Subsection 1.1.1
  * Section 1.2
* Chapter 2
  * Section 2.1

Configuration

[MD007]
indent = 2  # Number of spaces per indentation level (default: 2)
start-indented = false  # Allow first level lists to start indented (default: false)
start-indent = 2  # Number of spaces for first level when start_indented is true (default: 2)
style = "text-aligned"  # Indentation style: "text-aligned" (default) or "fixed" (default: "text-aligned")

Configuration options explained

  • indent: The number of spaces to use for each level of list nesting
  • start-indented: When true, allows the first level of lists to be indented instead of starting at column 0
  • start-indent: When start-indented is true, this specifies how many spaces the first level should be indented
  • style: Controls how nested list indentation is calculated (see Style Options below)

"Do What I Mean" Behavior

When you set indent without explicitly setting style, rumdl uses fixed style automatically. This ensures your configured indent value is actually used:

[MD007]
indent = 4  # This will use 4-space increments (fixed style)

Why this matters: Without this behavior, setting indent = 4 would have no effect because the default text-aligned style ignores the indent value and instead aligns nested items with the parent's text content.

If you explicitly set both indent and style = "text-aligned", a warning will be shown because this combination is contradictory (text-aligned ignores indent).

Mixed Lists: Ordered and Unordered

When you have bullets nested under ordered lists, the bullets always use text-aligned positioning, even if you've set a specific indent value. This is because ordered list markers have variable widths (1. vs 10. vs 100.), making fixed indentation impractical.

[MD007]
indent = 4  # Used for bullets under bullets

* Bullet item
    * Nested bullet (4-space fixed indent - uses your config)
        1. Ordered child
           * Bullet under ordered (text-aligned at column 11, not fixed)

In this example:

  • The second bullet uses 4-space indent (your configured value)
  • The bullet under the ordered item aligns with "Ordered" text, not at a fixed 12-space position

This ensures proper visual alignment regardless of whether the parent is 1. or 100..

Style Options

The style option determines how indentation is calculated for nested list items:

text-aligned (default - rumdl style)

Nested list items align their markers with the parent item's text content. This creates visually aligned text that's easy to read.

* Parent item
  * Child aligns with "Parent" text (2 spaces from start)
    * Grandchild aligns with "Child" text (4 spaces from start)

Why this is the default:

  • More readable in source code
  • Child text naturally aligns with parent text
  • Follows the visual hierarchy of the content

fixed (markdownlint compatible)

Uses fixed multiples of the indent value for each nesting level, regardless of parent content position. This is how markdownlint behaves.

* Parent item
  * Child at indent×1 (2 spaces)
    * Grandchild at indent×2 (4 spaces)

When to use fixed:

  • You're migrating from markdownlint and want identical behavior
  • You prefer strict mathematical multiples
  • Your team uses markdownlint and you want consistency

Example: Difference between styles

With a 3-character marker like 1.:

text-aligned:

1. First item
   * Child marker aligns where "First" starts (3 spaces)
     * Grandchild aligns where "Child" starts (5 spaces)

fixed (indent = 2):

1. First item
  * Child at 2 spaces (indent × 1)
    * Grandchild at 4 spaces (indent × 2)

Example with start-indented: true

[MD007]
indent = 2
start-indented = true
start-indent = 4

With this configuration, the following is valid:

Some paragraph text.

    * First level item (4 spaces indent)
      * Second level item (6 spaces total: 4 + 2)
        * Third level item (8 spaces total: 4 + 2 + 2)
    * Another first level item

Automatic fixes

This rule automatically adjusts the indentation of nested list items to use exactly 2 spaces (or your configured value) per nesting level.

Learn more

  • MD004 - Use consistent markers for unordered lists
  • MD005 - Keep list indentation consistent
  • MD006 - Start lists at the beginning of the line