Skip to content

MD025 - single-title

Description

This rule checks that only one top-level heading (h1 by default) exists in a document. It triggers when multiple h1 headings are found, as only one should serve as the document title. The level parameter can be used to change the top-level heading (e.g. to h2) in cases where an h1 is added externally by the rendering platform.

Sites that render a front matter title as the page's top-level heading can set front_matter_title to a regex such as ^title\s*[:=]. If the front matter has a matching line, it is treated as the top-level heading, so any top-level heading in the document body is reported. This is off by default, because many renderers (GitHub, MkDocs) do not show the title as a heading, and the body heading is then the only one.

Fixable: No

Rationale

A top-level heading serves as the title for the document. If this convention is followed, there should only be one title, and the entire document should be contained within it. Having multiple top-level headings breaks document hierarchy and can confuse readers and tools that generate tables of contents.

Configuration

level

Heading level to treat as top-level (1-6). Default is 1 (h1).

  • Default: 1
front_matter_title

Regex pattern to match title in front matter, for example '^title\s*[:=]'. If front matter contains a matching line, it is treated as the top-level heading. Empty (the default) to disable.

  • Default: "" (empty string)

Examples

Invalid

# First Title

Some content.

# Second Title

This document has multiple top-level headings.

Valid

# Document Title

## First Section

Some content here.

## Second Section

More content here.