# 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

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

### ❌ Incorrect

<!-- rumdl-disable MD007 -->

```markdown
* 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)

```

<!-- rumdl-enable MD007 -->

### 🔧 Fixed

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

## Configuration

```toml
[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:

```toml
[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 and `style` is not explicitly `"fixed"`, the
bullets **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. With an explicit `style = "fixed"`, bullets under ordered lists are
checked against the fixed indent clamped to the parent's content column (see the `fixed` style
below).

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

```markdown
* 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.

```markdown
* 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.

```markdown
* 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

**Bullets under ordered lists are clamped.** A bullet cannot sit to the left of its parent's
content column without leaving the item, so under an ordered parent the expected indent is the
larger of the fixed value and the parent's content column. With `indent = 2` under `1. `, the
fixed value would be 2 but the content column is 3, so 3 is expected; deeper levels build on the
corrected position of their parent. This keeps autofixes from restructuring the document.

#### Example: Difference between styles

With a 3-character marker like `1.`:

**text-aligned:**

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

**fixed (indent = 2):**

```markdown
1. First item
   * Child at 3 spaces (fixed 2 clamped to the parent's content column)
     * Grandchild at 5 spaces (fixed 4 clamped to the child's content column)
```

**fixed (indent = 4):**

```markdown
1. First item
    * Child at 4 spaces (indent × 1, already past the content column)
        * Grandchild at 8 spaces (indent × 2)
```

### Example with start-indented: true

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

With this configuration, the following is valid:

```markdown
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

- [Lists in Markdown](https://www.markdownguide.org/basic-syntax/#lists-1) - How to create well-formatted lists
- [CommonMark specification](https://spec.commonmark.org/0.31.2/#list-items) - Technical details about list formatting

## Related rules

- [MD004](md004.md) - Use consistent markers for unordered lists
- [MD005](md005.md) - Keep list indentation consistent
