Linter · Rules

markdown/no-duplicate-headings

Disallow duplicate headings in the same document

Sites that render Markdown create an anchor for each heading. Two headings with the same text get anchors like #options and #options-1, and which is which changes as soon as a section moves. A table of contents with the same entry twice doesn't help a reader either.

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-duplicate-headings": "error" },
  },
];

It also works with markdown/gfm.

Examples

Reported:

# Server

## Options

# Client

## Options

Not reported:

# Server

## Server options

# Client

## Client options

Options

Option	Default	What it does
`checkSiblingsOnly`	`false`	Only compare a heading with the others in the same parent section.

# Server

## Options

# Client

## Options

# Server

## Options

## Options