[GH-ISSUE #300] no-duplicate-heading comparing non-sibling headers #2106

New issue

Closed

opened 2026-03-07 20:04:37 +03:00 by kerem · 4 comments

kerem commented

2026-03-07 20:04:37 +03:00

Owner

Originally created by @MatthewHerbst on GitHub (Jun 23, 2020).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/300

This might be the desired behavior, however, it is not obvious to me that it would be so.

Given the following file:

# How it works

Some content here

# Random header

Some content here

## How it works

Some content here

The second How it works header gives the error (in VSCode) MD024/no-duplicate-heading/no-duplicate-header: Multiple headings with the same content.

I feel that this rule should only apply to headers that are siblings. Is the current behavior expected, or is it a bug?

Originally created by @MatthewHerbst on GitHub (Jun 23, 2020). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/300 This might be the desired behavior, however, it is not obvious to me that it would be so. Given the following file: ```md # How it works Some content here # Random header Some content here ## How it works Some content here ``` The second `How it works` header gives the error (in VSCode) `MD024/no-duplicate-heading/no-duplicate-header: Multiple headings with the same content`. I feel that this rule should only apply to headers that are siblings. Is the current behavior expected, or is it a bug?

kerem

2026-03-07 20:04:37 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:04:38 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 23, 2020):

What you are seeing is expected behavior. It is the first example in the rule documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content

There is a siblings_only parameter (also shown there) for the specific scenario of release notes, but it is almost the opposite of what you are asking about.

Why would one want to allow duplicates just because they are at different nesting levels?

@DavidAnson commented on GitHub (Jun 23, 2020): What you are seeing is expected behavior. It is the first example in the rule documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content There is a `siblings_only` parameter (also shown there) for the specific scenario of release notes, but it is almost the opposite of what you are asking about. Why would one want to allow duplicates just because they are at different nesting levels?

kerem commented

2026-03-07 20:04:38 +03:00

Author

Owner

@MatthewHerbst commented on GitHub (Jun 23, 2020):

My mistake for not seeing that in the docs, apologies. And because we have a document along the lines of:

# Thing 1

## What we use it for
## How it works

# Thing 2

## What we use it for
## How it works

@MatthewHerbst commented on GitHub (Jun 23, 2020): My mistake for not seeing that in the docs, apologies. And because we have a document along the lines of: ```md # Thing 1 ## What we use it for ## How it works # Thing 2 ## What we use it for ## How it works ```

kerem commented

2026-03-07 20:04:38 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jun 23, 2020):

What you show there looks like the scenario for siblings_only - you may be in luck!

@DavidAnson commented on GitHub (Jun 23, 2020): What you show there looks like the scenario for `siblings_only` - you may be in luck!

kerem commented

2026-03-07 20:04:38 +03:00

Author

Owner

@MatthewHerbst commented on GitHub (Jun 23, 2020):

I think so! Thanks again for pointing that out, and for maintaining the package 👍

@MatthewHerbst commented on GitHub (Jun 23, 2020): I think so! Thanks again for pointing that out, and for maintaining the package 👍