MD002 - First Heading H1
First heading should be a top-level heading (H1).
Deprecated: This rule is superseded by MD041 which offers an improved implementation. Consider using MD041 instead.
Why This Rule Exists
Documents should start with a top-level heading (H1) to establish proper hierarchy. This ensures consistent document structure and helps screen readers and document outlines understand the content organization.
Examples
Incorrect
## Introduction
This document starts with an H2.
Correct
# Document Title
## Introduction
The document properly starts with an H1.
Configuration
[MD002]
level = 1 # Expected first heading level (default: 1)
When to Disable
- When using MD041 instead (recommended)
- Documents that are fragments or partials
- Auto-generated content with different conventions
Rule Details
- Rule ID: MD002
- Aliases: first-heading-h1
- Category: Structure
- Severity: Warning
- Auto-fix: Yes (can add H1 if missing)
- Deprecated: Yes (use MD041)