[GH-ISSUE #113] Header vs. heading #94

New issue

Closed

opened 2026-03-03 01:23:40 +03:00 by kerem · 2 comments

kerem commented

2026-03-03 01:23:40 +03:00

Owner

Originally created by @levacic on GitHub (Mar 18, 2018).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/113

This library seems to misuse the word "header" a lot, when in fact, as far as I can see, it always actually refers to a "heading". This is a common mistake all over the web (and a personal pet peeve of mine), but both the HTML standard and the CommonMark spec correctly refer to these tags as headings, whereas a header is something completely different, and even has its own HTML tag.

I realize this is because the original https://github.com/markdownlint/markdownlint library does the same, and I've created an issue there as well - markdownlint/markdownlint#194 - but that seems to be a less maintained repo, as it hasn't seen new commits in over half a year - this package seems to be more popular, especially as Node-based build systems are more common these days.

Apart from the fact that it's technically incorrect, I've also seen it cause actual confusion in practice. I'm pretty sure this change would be a BC-break, because it would require changing the naming of tags and aliases for the affected rules, but are you open to fixing the naming inconsistency at some point in the future? Furthermore, are you okay with a moving the direction of this project away from the original library by implementing a change like this?

Originally created by @levacic on GitHub (Mar 18, 2018). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/113 This library seems to misuse the word "header" a lot, when in fact, as far as I can see, it always actually refers to a "heading". This is a common mistake all over the web (and a personal pet peeve of mine), but both the [HTML standard](https://www.w3.org/TR/2011/WD-html-markup-20110525/elements.html) and the [CommonMark spec](http://spec.commonmark.org/0.28/#atx-headings) correctly refer to these tags as headings, whereas a header is something completely different, and even has its own [HTML tag](https://www.w3.org/TR/2011/WD-html-markup-20110525/header.html#header). I realize this is because the original https://github.com/markdownlint/markdownlint library does the same, and I've created an issue there as well - markdownlint/markdownlint#194 - but that seems to be a less maintained repo, as it hasn't seen new commits in over half a year - this package seems to be more popular, especially as Node-based build systems are more common these days. Apart from the fact that it's technically incorrect, I've also seen it cause actual confusion in practice. I'm pretty sure this change would be a BC-break, because it would require changing the naming of tags and aliases for the affected rules, but are you open to fixing the naming inconsistency at some point in the future? Furthermore, are you okay with a moving the direction of this project away from the original library by implementing a change like this?

kerem

2026-03-03 01:23:40 +03:00

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

2026-03-03 01:23:41 +03:00

Author

Owner

@DavidAnson commented on GitHub (Mar 18, 2018):

Yes, I’m open to this proposal, I prefer being correct whenever possible. :) This library (now) supports multiple names for a rule, so it should be possible to add corrected names without removing the current ones. Rule description changes should not be breaking.

If you have additional guidance about what should change, please let me know - otherwise it seems that you’d suggest bulk-replacing “header” with “heading” pretty much everywhere?

@DavidAnson commented on GitHub (Mar 18, 2018): Yes, I’m open to this proposal, I prefer being correct whenever possible. :) This library (now) supports multiple names for a rule, so it should be possible to add corrected names without removing the current ones. Rule description changes should not be breaking. If you have additional guidance about what should change, please let me know - otherwise it seems that you’d suggest bulk-replacing “header” with “heading” pretty much everywhere?

kerem commented

2026-03-03 01:23:41 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 13, 2018):

Merged next branch.

@DavidAnson commented on GitHub (May 13, 2018): Merged next branch.

kerem referenced this issue

2026-03-07 20:02:49 +03:00

[GH-ISSUE #94] MD003/header-style: bug, setext followed by atx flagged as error with setext_with_atx setting. #1925