# 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.

{/* Generated by src/codegen/lint-rule-docs.ts. Do not edit this section. */}

## Configure

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

{/* skip */}

```js 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`.

{/* End of the generated section. */}

## Examples

Reported:

{/* bad */}

```md
# Bun

# Install
```

{/* bad */}

```md
# Bun

<h1>Install</h1>
```

Not reported:

{/* good */}

```md
# Bun

## Install
```

## Options

| Option             | Default                                                | What it does                                                                                                                         |
| ------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `frontmatterTitle` | a 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.

{/* bad {"languageOptions": { "frontmatter": "yaml" }} */}

```md
---
title: Bun
---

# Install
```

{/* good {"languageOptions": { "frontmatter": "yaml" }, "options": [{ "frontmatterTitle": "" }]} */}

```md
---
title: Bun
---

# Install
```