MD041 - first-line-heading

Description

This rule checks that the first line in a document is a top-level heading (h1 by default). The heading can be ATX-style (# Title), setext-style (underlined with ===), or an HTML heading element (<h1>Title</h1>). Blank lines and HTML comments before the heading are allowed.

If YAML or TOML front matter contains a title (matched by the front_matter_title regex pattern), the rule is satisfied without requiring a heading in the document body. Set front_matter_title to an empty string to disable this behavior.

When allow_preamble is enabled, non-heading content before the first heading is permitted and only the heading's level is checked.

Rationale

The top-level heading often acts as the title of a document. Having a clear title at the beginning helps readers understand the document's purpose and enables tools like static site generators to extract titles. Documents without a proper title heading may appear incomplete or confusing in navigation menus and search results.

Configuration

level

Heading level expected as the first heading (1-6). Default is 1 (h1). Values outside this range are treated as 1.

• Default: 1

front_matter_title

Regex pattern to match title in front matter. If front matter contains a matching line, the rule passes. Set to empty string to disable front matter title check.

• Default: ^\s*title\s*[:=]

allow_preamble

Allow content before the first heading. When enabled, non-heading content before the first heading is ignored and only the first heading's level is checked.

• Default: false

Examples

Invalid

This document does not start with a heading.

# Title Comes Too Late

The heading should be at the beginning.

Valid

# Document Title

This document starts with a top-level heading.