MD024 - Avoid duplicate heading text¶
Aliases: no-duplicate-heading
What this rule does¶
Checks that headings don't have identical text, preventing confusion and navigation issues.
Why this matters¶
- Better navigation: Unique headings make it easier to find specific sections
- Clear table of contents: Automated TOCs need unique headings to create proper links
- Improved accessibility: Screen readers rely on unique headings for navigation
- Avoid confusion: Readers won't wonder which "Introduction" section they're in
Examples¶
✅ Correct¶
# Project Setup
## Installing Dependencies
Details about npm install...
## Configuring the Environment
Details about environment setup...
## Running Tests
How to run the test suite...
❌ Incorrect¶
# Project Setup
## Setup
Details about npm install...
## Setup
Details about environment setup...
## Setup
How to run the test suite...
🔧 Fixed¶
# Project Setup
## Installing Dependencies
Details about npm install...
## Environment Configuration
Details about environment setup...
## Test Setup
How to run the test suite...
Configuration¶
[MD024]
allow-different-nesting = false # Allow duplicates at different levels (default: false)
siblings-only = true # Only check siblings at same level (default: true)
Note: rumdl defaults siblings-only to true (unlike markdownlint's false ) to reduce false positives in CHANGELOGs and structured documentation. To match markdownlint's stricter behavior, set
siblings-only = false .
Automatic fixes¶
This rule cannot be automatically fixed because changing heading text requires understanding the content's meaning. You'll need to manually update duplicate headings to be more descriptive.