[GH-ISSUE #1042] MD003 "consistent" doesn't allow "setext_with_atx" #2449

New issue

Closed

opened 2026-03-07 20:07:52 +03:00 by kerem · 3 comments

kerem commented

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

Owner

Originally created by @Tweekism on GitHub (Nov 16, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1042

Hi,

I've noticed when set to the default value of consistent you aren't allowed to do:-

Title
=====

Heading
-------

### Subheading

Even thought that would be 'consistent' with the setext_with_atx style, which we use for our plain text readable documentation.

MD003/heading-style/header-style: Heading style [Expected: setext; Actual: atx]markdownlintMD003

In other words, consistent only allows either atx or setext.

Assuming that is the intended result, is there a setting that would allow either atx, setext or setext_with_atx as long as it is consistent within the one document (as setext doesn't have a way to do headings past H3)?

Originally created by @Tweekism on GitHub (Nov 16, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1042 Hi, I've noticed when set to the default value of ***consistent*** you aren't allowed to do:- ``` Title ===== Heading ------- ### Subheading ``` Even thought that would be 'consistent' with the setext_with_atx style, which we use for our plain text readable documentation. > MD003/heading-style/header-style: Heading style [Expected: setext; Actual: atx]markdownlint[MD003](https://github.com/DavidAnson/markdownlint/blob/v0.31.1/doc/md003.md) In other words, ***consistent*** only allows either **atx** or **setext**. Assuming that is the intended result, is there a setting that would allow either **atx**, **setext** or **setext_with_atx** as long as it is consistent within the one document (as setext doesn't have a way to do headings past H3)?

kerem

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

closed this issue
added the
question
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Nov 16, 2023):

Your summary of the behavior of "consistent" is correct; it requires that the first style it encounters hold for the rest of the document.

I don't know of a setting that would allow all three flavors like you describe. That said, it sounds like your project prefers "setext_with_atx", so I am not sure why you wouldn't set that in your configuration?

@DavidAnson commented on GitHub (Nov 16, 2023): Your summary of the behavior of "consistent" is correct; it requires that the first style it encounters hold for the rest of the document. I don't know of a setting that would allow all three flavors like you describe. That said, it sounds like your project prefers "setext_with_atx", so I am not sure why you wouldn't set that in your configuration?

kerem commented

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

Author

Owner

@Tweekism commented on GitHub (Nov 16, 2023):

Fair point, I've set that in our VSCode workspace settings for the project.

I guess my question was more about whether or not setext_with_atx in itself should be considered a consistent style since level 1 headers are reserved for the page title that leaves you with only 1 level of headings for the body (level 2) if you are using setext only.

But maybe that doesn't really make since from a standards perspective, and seems like perhaps atx style headings are winning out in the popular landscape anyway so maybe I'm just questioning my own life decisions.

Happy to close, reason: "Original poster slowly losing his sanity"

@Tweekism commented on GitHub (Nov 16, 2023): Fair point, I've set that in our VSCode workspace settings for the project. I guess my question was more about whether or not setext_with_atx in itself should be considered a consistent style since level 1 headers are reserved for the page title that leaves you with only 1 level of headings for the body (level 2) if you are using setext only. But maybe that doesn't really make since from a standards perspective, and seems like perhaps atx style headings are winning out in the popular landscape anyway so maybe I'm just questioning my own life decisions. Happy to close, reason: "Original poster slowly losing his sanity"

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Nov 16, 2023):

It's an interesting scenario and something I hadn't realized! It's possible to implement, but it would be slightly messy and besides, I'm not even sure I'd consider a mixed style like that to be "consistent" anyway. So yes, my inclination is to close this as "unplanned".

@DavidAnson commented on GitHub (Nov 16, 2023): It's an interesting scenario and something I hadn't realized! It's possible to implement, but it would be slightly messy and besides, I'm not even sure I'd consider a mixed style like that to be "consistent" anyway. So yes, my inclination is to close this as "unplanned".