[GH-ISSUE #1601] no-duplicate-heading: Enable siblings_only by default? #716

New issue

Closed

opened 2026-03-03 01:29:18 +03:00 by kerem · 3 comments

kerem commented

2026-03-03 01:29:18 +03:00

Owner

Originally created by @JoshuaKGoldberg on GitHub (May 12, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1601

MD024 / no-duplicate-heading includes a siblings_only property:

github.com/DavidAnson/markdownlint@224987d727/doc/Rules.md (L806)

Is there a reason this is on by default? Duplicate non-sibling headings are not necessarily an issue. For common terms like ## API -> ### (feature) -> #### Examples, it can sometimes make more sense to be consistent with headings across sections.

Example resource discussing how non-sibling duplicates are not necessarily an accessibility issue: https://www.tpgi.com/heading-off-confusion-when-do-headings-fail-wcag

Related issues: #300, #1591

Originally created by @JoshuaKGoldberg on GitHub (May 12, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1601 [MD024 / no-duplicate-heading](https://github.com/DavidAnson/markdownlint/blob/224987d727ebada36752074d2466a061c9e03ff0/doc/Rules.md#md024---multiple-headings-with-the-same-content) includes a `siblings_only` property: https://github.com/DavidAnson/markdownlint/blob/224987d727ebada36752074d2466a061c9e03ff0/doc/Rules.md?plain=1#L806 Is there a reason this is on by default? Duplicate _non-sibling_ headings are not necessarily an issue. For common terms like `## API` -> `### (feature)` -> `#### Examples`, it can sometimes make more sense to be consistent with headings across sections. Example resource discussing how non-sibling duplicates are not necessarily an accessibility issue: https://www.tpgi.com/heading-off-confusion-when-do-headings-fail-wcag Related issues: #300, #1591 Related comment in the wild: https://github.com/JoshuaKGoldberg/package-json-validator/pull/230#discussion_r2085067204

kerem

2026-03-03 01:29:18 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:29:19 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 12, 2025):

That setting did not used to exist and was added in response to the changelog pattern you cite. Because the rule is ultimately about not duplicating headings, the default behavior is to not duplicate ANY headings. For people in the nested scenario, they can opt in.

@DavidAnson commented on GitHub (May 12, 2025): That setting did not used to exist and was added in response to the changelog pattern you cite. Because the rule is ultimately about not duplicating headings, the default behavior is to not duplicate ANY headings. For people in the nested scenario, they can opt in.

kerem commented

2026-03-03 01:29:19 +03:00

Author

Owner

@JoshuaKGoldberg commented on GitHub (May 12, 2025):

the default behavior is to not duplicate ANY headings

Can I ask, why? 🙂

As in, what is the set of reasons to enable the rule - and which of those reasons still apply to non-siblings?

@JoshuaKGoldberg commented on GitHub (May 12, 2025): > the default behavior is to not duplicate ANY headings Can I ask, why? 🙂 As in, what is the set of reasons to enable the rule - and which of those reasons still apply to non-siblings?

kerem commented

2026-03-03 01:29:19 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 12, 2025):

Quoting the documentation:

Rationale: Some Markdown parsers generate anchors for headings based on the heading name; headings with the same content can cause problems with that.

I can't say which parsers, or whether they still have this problem.

@DavidAnson commented on GitHub (May 12, 2025): Quoting the documentation: > Rationale: Some Markdown parsers generate anchors for headings based on the heading name; headings with the same content can cause problems with that. I can't say which parsers, or whether they still have this problem.

kerem referenced this issue

2026-03-07 20:07:06 +03:00

[GH-ISSUE #716] Is prettier redundant if I use markdownlint? #2367