setext_with_atx fails for documents that are pure atx

[francescalb]

According to the documentation the heading style "rule is triggered when different heading styles are used in the same document". Also:
"The setext_with_atx and setext_with_atx_closed settings allow ATX-style headings of level 3 or more in documents with setext-style headings (which only support level 1 and 2 headings)"

However, we have repository in which some of the .md files use setext_with_atx (for level 3 header) and some use atx. This means that no matter which setting I use, either one set of the .md files will trigger errors or the other. Is there a way for the system to only check one document at a time. as per the documentation?

[DavidAnson]

The documentation describes behavior within a single document. That seems to reflect what you are seeing, so I don't understand what about the documentation you think is wrong. Can you clarify, please?

Regarding your scenario of wanting to lint some files with one set of rules and other files with a different set, an approach that works well (if they are in separate parts of your project) is to add an additional configuration file at whatever place in the tree is relevant to adjust the configuration. For example, the root directory may have a configuration for rule set A while one of its subdirectories has another configuration that adjusts that to B for the files within.

However, if you have files of both types spread randomly throughout the project, it might be easier to run the linter in two passes. The first pass should address one set of files with the relevant configuration for them while the second pass can address the other files with their own different configuration.

You could also customize this rule in whatever files need it using the comment syntax - assuming there are relatively few of them or you don't mind updating them all.

Finally, you might consider unifying the heading style across your project because consistency is generally a good thing and rules like this one make it easy to enforce.

[francescalb]

Thank you for the clarification. I considered one file = one document, but that is clearly not the case. In projects with strong-willed contributors it is difficult to force everyone to do exaclty the same, and some thigns are more important that other. Originally, my idea was to force consistency withing one .md file but not force this across the whole project, but I might need to reevaluate. Thank you for the thorough answer.