structure/initial-heading

Requires the first block of a document, after optional YAML or TOML front matter, to be a level-1 heading. Underlined (===) headings count as well as # headings.

Problem rule, reported only. Presets: none. Dialects: all. Options: level, allowPreamble, frontMatterTitle.

Reported:

Some text before the title.

# Title

Not reported:

---
title: Notes
---

# Notes

Option	Values	Default
level	An integer from 1 to 6	1
allowPreamble	true or false	false
frontMatterTitle	true, false, or a regular expression as string	false

• level: the required heading level.
• allowPreamble: with true, prose and comments may precede the first top-level Markdown heading, which must have that level. A document with no heading is still reported unless a recognized front-matter title satisfies the check.
• frontMatterTitle: the default, false, requires a body heading even when metadata contains a title. true lets a top-level YAML or TOML title key satisfy the check; a JavaScript regular-expression string such as "^page_name\\s*[:=]" recognizes a different field. The pattern matches the front matter's contents, without its delimiters, in multiline mode; it does not match the body. An invalid pattern is a configuration error. false or "" disables title recognition. The same setting is available on structure/single-title, with a different default, and on structure/heading-increment, with the same default.

Edge cases and advanced usage

Details: an empty document is reported. Comments and other content before the title are not skipped. A heading inside a list or quote does not supply the document's initial heading. The default title detector matches a literal title key, optionally quoted: in column 1 for YAML, or before the first table header in TOML, where indentation is allowed. It matches text rather than parsing the metadata; use a custom pattern for other textual forms. Use overrides to exempt generated documents.

During markdownlint fallback, MD041 also recognizes HTML headings. In a raw HTML block, a malformed opener can leave a later heading tag as the first tag that counts. Tags inside code spans, math or directive attributes do not count. Empty or comment-only documents pass, as does a permitted preamble without a heading. Wrapped multiline tags use the same inline reading. The native rule keeps its Markdown-only heading policy and reports a document with no heading.

Unusually deep block directives in that compatibility reading can reach a work limit. MD041 then reports that its HTML-flow inspection could not complete, without proposing an edit. Simplify the nesting or set MD041: false in the markdownlint configuration to skip that check. This limit does not affect the native rule.

Related rules

style/heading turns underlined headings into # headings.