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#

example.md1 problem
# Server

## Options

# Client

## Options
example.mdNo problems
# Server

## Server options

# Client

## Client options

Options#

OptionDefaultWhat it does
checkSiblingsOnlyfalseOnly compare a heading with the others in the same parent section.
example.mdwith { "checkSiblingsOnly": true }No problems
# Server

## Options

# Client

## Options
example.mdwith { "checkSiblingsOnly": true }1 problem
# Server

## Options

## Options