name: duplicate-heading default: true advisory: true fix: false since: 0.2.0

duplicate-heading

Two headings at the same level under the same parent with the same text.

What it does

Flags two or more headings whose slug (lowercase, hyphenated text) collide within the same document.

Why

Markdown renderers (GitHub, mdBook, GitLab) assign each heading a URL fragment derived from its text. Two headings with the same text collide on the fragment: only one is reachable, and which one depends on whether the renderer disambiguates with a -1 suffix or silently overwrites. External links to the document then drift unpredictably as new sections are added.

Example (bad)

## Examples

…

## Examples

Example (good)

## Examples

…

## More examples

Configuration

  • Disable inline: <!-- mdwright: allow duplicate-heading -->.
  • Disable in config: [lint] ignore = ["duplicate-heading"].
  • Severity: advisory. Math/theorem documents legitimately repeat ### Proof or ### Corollary under one chapter, so the diagnostic surfaces but does not fail mdwright check --check.

References

  • GitHub's slug algorithm: lowercase, replace whitespace with -, strip non-word characters.