# 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)
```
### 🔧 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