markdownlint "MD024/no-duplicate-heading" in CI

By Kaveh Alemi·Latchkey

markdownlint rule MD024 flags two headings with identical text because they generate colliding anchor slugs. Changelogs and repeated section names (Usage, Example) trip it. It exits non-zero.

What this error means

markdownlint fails with "MD024/no-duplicate-heading Multiple headings with the same content [Context: '## Usage']" where the same heading text appears more than once.

markdownlint

CHANGELOG.md:40 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Fixed"]

Common causes

Repeated section names across the document

Docs reuse "Usage", "Example", or a changelog reuses "Fixed"/"Added" under each version, producing duplicate heading text.

Default rule checks the whole document, not siblings

By default MD024 rejects any duplicate anywhere; repeated headings under different parents still collide.

How to fix it

Allow duplicates that are not siblings

Set siblings_only so repeated headings under different parents (like per-version changelog sections) are allowed.

.markdownlint.json

{
  "MD024": { "siblings_only": true }
}

Make the heading text unique

Rename one heading so anchors do not collide, for example "Usage (CLI)" and "Usage (API)".

guide.md

## Usage (CLI)
...
## Usage (API)

How to prevent it

Enable siblings_only for changelogs and repeated section layouts.
Give repeated concepts distinct heading text so anchors stay unique.
Run markdownlint in pre-commit so duplicates are caught before CI.

Frequently asked questions

What causes ""MD024/no-duplicate-heading""?