markdown/no-multiple-h1

Disallow multiple H1 headings in the same document

The level 1 heading is the title of the document. Search engines, screen readers and documentation tools expect one. A second one is usually a section that should be level 2.

<h1> elements in HTML count, and so does a title in the front matter.

Configure#

Off by default. It needs an ESLint config that says which files are in the language:

eslint.config.js
import markdown from "@eslint/markdown";

export default [
  {
    files: ["**/*.md"],
    plugins: { markdown },
    language: "markdown/commonmark",
    rules: { "markdown/no-multiple-h1": "error" },
  },
];

It also works with markdown/gfm.

Examples#

example.md1 problem
# Bun

# Install
example.md1 problem
# Bun

<h1>Install</h1>
example.mdNo problems
# Bun

## Install

Options#

OptionDefaultWhat it does
frontmatterTitlea pattern that matches title:, title =, "title":A regular expression. If a line of the front matter matches it, the front matter counts as a level 1 heading. "" turns that off.

Front matter is only parsed if languageOptions.frontmatter is set to the format that the files use.

example.md1 problem
---
title: Bun
---

# Install
example.mdwith { "frontmatterTitle": "" }No problems
---
title: Bun
---

# Install