DavidAnson
no-duplicate-heading: Enable siblings_only by default?
MD024 / no-duplicate-heading 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
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.
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?
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.