[GH-ISSUE #1591] MD024: Allow defining `siblings_only` per level #2565

New issue

Open

opened 2026-03-07 20:08:55 +03:00 by kerem · 0 comments

kerem commented

2026-03-07 20:08:55 +03:00

Owner

Originally created by @alonso-herreros on GitHub (May 5, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1591

I like rule MD024, it's specially useful when your document includes a Table of Contents. However, I have ran into a case where I want to keep siblings_only turned off only until a certain heading level, say h4. In my case, h4s are left out of the Table of Contents, it's too deep, so I have no need for them to be unique. It's a case similar to a changelog; in this case many of my h3 sections need the same h4 subsections, which should be unique between siblings but not globally.

Example

Here's an example where level 4 headings could be allowed to be duplicate globally as long as they're unique between siblings.

# Title

## Table of Contents

* [Section 1](#section-1)
    * [Section 1.A](#section-1-a)
    * [Section 1.B](#section-1-b)

## Section 1

### Section 1.A

#### Subsection X

#### Subsection Y

### Section 1.B

#### Subsection X

#### Subsection Y

Proposal

I think a good solution would be allowing siblings_only to take a list of integers as a value, which would indicate the levels where only siblings are required to be unique.

For backwards-compatibility, true would mean all levels, while false (or an empty list) would mean none.

Also, a nice option could be interpreting a single integer as 'that level and below'. A 0 or a 1 would be equivalent to true.

Skipping a level while also indicating 'and below' would not be possible (e.g. level 3 plus 5 and below), but I think this is too rare to worry about, an you can get the same functionality by just specifying all levels you use.

Originally created by @alonso-herreros on GitHub (May 5, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1591 I like [rule MD024](https://github.com/DavidAnson/markdownlint/blob/main/doc/md024.md), it's specially useful when your document includes a Table of Contents. However, I have ran into a case where I want to keep `siblings_only` turned off only until a certain heading level, say `h4`. In my case, `h4`s are left out of the Table of Contents, it's too deep, so I have no need for them to be unique. It's a case similar to a changelog; in this case many of my `h3` sections need the same `h4` subsections, which should be unique between siblings but not globally. ## Example Here's an example where level 4 headings could be allowed to be duplicate globally as long as they're unique between siblings. ```markdown # Title ## Table of Contents * [Section 1](#section-1) * [Section 1.A](#section-1-a) * [Section 1.B](#section-1-b) ## Section 1 ### Section 1.A #### Subsection X #### Subsection Y ### Section 1.B #### Subsection X #### Subsection Y ``` ## Proposal I think a good solution would be **allowing `siblings_only` to take a list of integers as a value**, which would indicate **the levels where only siblings are required to be unique**. For backwards-compatibility, `true` would mean all levels, while `false` (or an empty list) would mean none. Also, a nice option could be interpreting **a single integer as 'that level and below'**. A `0` or a `1` would be equivalent to `true`. Skipping a level while also indicating 'and below' would not be possible (e.g. level 3 plus 5 and below), but I think this is too rare to worry about, an you can get the same functionality by just specifying all levels you use.