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
allow-preamble = false # Allow content before the first heading (default: false)
fix = false # Enable auto-fix (default: false)
allow-preamble¶
With allow-preamble = true, the document no longer has to open with a heading. The rule instead finds the document's first top-level heading and checks its level:
That document is clean with allow-preamble = true and flagged without it. A wrong level is still reported, at the line of the heading itself rather than line 1:
A document with no top-level heading at all is not flagged when allow-preamble = true. Headings that only appear inside a container (a list, a blockquote, an HTML block) do not count as the document's first heading, so a document whose only heading is nested is treated the same as one with no heading.
Automatic fixes¶
By default, this rule does not provide automatic fixes because adding a document title is typically a content decision. However, you can enable opt-in auto-fix with fix = true.
When enabled, the fixer will:
- Fix wrong heading level: If the first content is a heading with the wrong level (e.g.,
## Titlewhen level 1 is required), rewrite it to the correct level (# Title) - Move heading above preamble: If a heading appears after only "preamble" (blank lines, HTML comments), move it to the start of the content
With allow-preamble = true the fixer only ever does the first of these: the heading is rewritten to the required level where it stands. Moving it to the top would delete the preamble that the option exists to permit.
The fixer will not change content when:
- There is no heading in the document (cannot invent content)
- Real content appears before the first heading (unsafe to move)
- The document already has the correct heading at the correct position
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 - In MkDocs flavor, anchor lines like
[](){ #anchor }are skipped as non-content