MD041 - Start Your Document with a Clear Title¶
Aliases: first-line-heading, first-line-h1
What this rule does¶
Ensures every document begins with a top-level heading (like # Title), giving your document a clear title and purpose from the start.
Why this matters¶
- Professional appearance: Documents without titles look incomplete and unprofessional
- Better navigation: Readers and tools can quickly identify what the document is about
- Improved SEO: Search engines and documentation systems rely on document titles
- Consistent structure: All documents in your project will have a uniform starting point
Examples¶
✅ Correct¶
Also correct with HTML headings:
Also correct with HTML comments before the heading:
<!-- This is a comment -->
# Getting Started Guide
Welcome to our documentation! This guide will help you...
❌ Incorrect¶
Welcome to our documentation! This guide will help you...
## Installation
First, install the dependencies...
🔧 Fixed¶
# Documentation
Welcome to our documentation! This guide will help you...
## Installation
First, install the dependencies...
Configuration¶
[MD041]
level = 1 # Heading level required (1-6, default: 1)
front-matter-title = "title" # Front matter field to use as title
front-matter-title-pattern = "^(title|header):" # Regex pattern to match title fields in front matter
Automatic fixes¶
This rule does not provide automatic fixes. Adding a document title is a content decision that should be made by the author because:
- Generic placeholders like
# Titleprovide no value and require manual replacement anyway - Some files intentionally don't have titles (includes, SUMMARY.md for MkDocs, partial content files, etc.)
- The tool cannot determine an appropriate title from the document content
Special cases¶
- Documents with front matter containing a title field are considered valid
- Empty documents are not checked
- HTML comments at the start are ignored when checking
- HTML heading tags (e.g.,
<h1>Title</h1>) are recognized as valid headings - The
front_matter_title_patternallows custom regex patterns for matching title fields