MD041 - First Line Top-Level Heading
First line in a file should be a top-level heading.
Why This Rule Exists
Documents should start with a title heading to establish context. This helps with document navigation, accessibility, and table of contents generation.
Examples
Incorrect
Some introductory text before the heading.
# Document Title
Content here.
Correct
# Document Title
Some introductory text.
Content here.
With Front Matter
---
title: My Document
---
# Document Title
Content here.
Configuration
[MD041]
level = 1 # Expected heading level (default: 1)
front_matter_title = "^\\s*title\\s*[:=]" # Regex for front matter title
If front_matter_title matches, the document is considered to have a title
and the rule passes.
When to Disable
- Fragment documents included in larger documents
- Files with front matter providing the title
- Auto-generated content with different structure
Rule Details
- Rule ID: MD041
- Aliases: first-line-heading, first-line-h1
- Category: Structure
- Severity: Warning
- Auto-fix: No
Replaces MD002
This rule supersedes MD002 with improved handling of front matter and more configuration options.