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.

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

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.