Skip to content

MD025 - Keep your document organized with one main title

Aliases: single-title, single-h1

What this rule does

Ensures your document has only one main title (heading level 1), maintaining a clear document hierarchy.

Why this matters

  • Clear hierarchy: One main title makes the document structure obvious to readers
  • Better navigation: Tools and readers can easily identify the document's primary topic
  • SEO benefits: Search engines expect one main title per page
  • Accessibility: Screen readers rely on proper heading hierarchy for navigation

Examples

✅ Correct

# Document Title

## Section 1

Content here.

## Section 2

More content here.

❌ Incorrect

# First Title

Content here.

# Second Title

More content here.

🔧 Fixed

# Document Title

## First Section

Content here.

## Second Section

More content here.

Configuration

[MD025]
level = 1                        # The heading level that should be unique (default: 1)
front-matter-title = "title"     # Regex pattern to match title in YAML front matter (default: "title")
allow-document-sections = false  # Allow multiple H1s separated by --- thematic breaks (default: false)
allow-with-separators = false    # Allow multiple H1s as document section titles (default: false)

Front Matter Integration

The front-matter-title option allows this rule to treat YAML front matter titles as H1 headings. This is useful for static site generators like Jekyll, Hugo, and Docusaurus that extract titles from front matter.

How it works:

  • When a document has YAML front matter with a title field, it counts as an H1
  • Subsequent H1 headings in the document body will trigger a violation
  • You can customize the field name by changing the regex pattern

Example with front matter:

---
title: My Blog Post
date: 2024-01-15
---

Content starts here without an H1 heading.

## First Section

This is valid because the front matter title counts as the H1.

Configuration examples:

# Match standard 'title:' field (default)
[MD025]
front-matter-title = "title"

# Match either 'title:' or 'heading:' fields
[MD025]
front-matter-title = "^\\s*(title|heading)\\s*[:=]"

# Disable front matter checking (treat front matter and body separately)
[MD025]
front-matter-title = ""

Headings inside blockquotes

Headings inside blockquotes (including nested quotes, a quote inside a list item and a list item inside a quote) count like headings inside list items. A quoted heading at the configured level is a title: the first title in the document is kept and every later one is reported, whether it is quoted or not, and a front matter title counts as the first. A quoted title is reported without a fix.

When an unquoted extra title is demoted, the quoted ATX headings in its section are demoted with it by rewriting only their # run, so the quote prefix and the document structure stay as they were. If the section holds a quoted setext heading, the fix for that title is withheld and only the warning is reported. A quoted heading at or above the configured level ends the section, and with allow-with-separators it counts as a heading between a separator and a later title.

Automatic fixes

This rule will:

  • Convert extra main titles to the next heading level (H1 → H2)
  • Preserve the document's first main title
  • Maintain the relative hierarchy of subsequent headings

Learn more