# MD025 - Keep your document organized with one main title

## What this rule does

Ensures your document has only one main title (heading level 1), maintaining a clear document hierarchy.

## Why this matters

- **Clear hierarchy**: One main title makes the document structure obvious to readers
- **Better navigation**: Tools and readers can easily identify the document's primary topic
- **SEO benefits**: Search engines expect one main title per page
- **Accessibility**: Screen readers rely on proper heading hierarchy for navigation

## Examples

### ✅ Correct

```markdown
# Document Title

## Section 1

Content here.

## Section 2

More content here.
```

### ❌ Incorrect

```markdown
# First Title

Content here.

# Second Title

More content here.
```

### 🔧 Fixed

```markdown
# Document Title

## First Section

Content here.

## Second Section

More content here.
```

## Configuration

```yaml
MD025:
  level: 1                    # The heading level that should be unique (default: 1)
  front-matter-title: "title" # Name of the front matter title field (default: "title")
```

## Automatic fixes

This rule will:

- Convert extra main titles to the next heading level (H1 → H2)
- Preserve the document's first main title
- Maintain the relative hierarchy of subsequent headings

## Learn more

- [CommonMark Spec: ATX headings](https://spec.commonmark.org/0.31.2/#atx-headings)
- [CommonMark Spec: Setext headings](https://spec.commonmark.org/0.31.2/#setext-headings)

## Related rules

- [MD001 - Keep heading levels organized](md001.md)
- [MD003 - Use consistent heading styles](md003.md)
- [MD024 - Avoid duplicate heading text](md024.md)
- [MD041 - Start files with a heading](md041.md)
