# 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, 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.

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

#### 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 2 spaces (indent × 1)
    * Grandchild at 4 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
- [MD006](md006.md) - Start lists at the beginning of the line
