[GH-ISSUE #990] MD012: Allow it (no-multiple-blanks) to work with MD022 (blanks-around-headings) #2429

New issue

Open

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

kerem commented

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

Owner

Originally created by @waldyrious on GitHub (Sep 27, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/990

This was previously proposed in the context of #305, but was beyond the scope of that issue. A new issue was recommended at the time, but I never got around to create one. Until now, that is 😄

The problem: currently setting MD022/blanks-around-headings to any value other than the default (1) can conflict with MD012/no-multiple-blanks, whose default value is 1.

In #305 the proposed workaround was to increase MD012/no-multiple-blanks's maximum to the number of lines specified for a heading; however, that makes it impossible to prevent the occurrence of multiple blank lines in other contexts.

One possible solution would be to have the values of MD022 override MD012's (similar to how in CSS more specific selectors override more generic ones); but perhaps that CSS analogy already hints at what would IMHO be a cleaner solution: since multiple blank lines around headings are a special case of multiple blanks, it seems reasonable to add parameters to MD012 to allow specifying custom values in that specific context. Something like this, for example:

no-multiple-blanks:
  maximum: 1
  headings_above: 2
  headings_below: 1

For prior art about rules that support parameters to apply differently in different contexts, see:

MD013/line-length, which supports the code_blocks, headings and tables parameters;
MD030/list-marker-space, which supports the ol_multi, ol_single, ul_multi and ul_single parameters
MD033/no-inline-html, which supports the allowed_elements parameter
and various others.

I don't think we need additional parameters for other elements, but I'll mention the possibility nevertheless in case it may be considered a more consistent approach overall: this proposal of extending MD012 could subsume not just MD022, but also MD028/no-blanks-blockquote, MD031/blanks-around-fences, and MD032/blanks-around-lists.

/cc @wedi

Originally created by @waldyrious on GitHub (Sep 27, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/990 This was previously proposed in the context of #305, but was beyond the scope of that issue. A new issue was recommended at the time, but I never got around to create one. Until now, that is :smile: **The problem:** currently setting [MD022](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md022)/blanks-around-headings to any value other than the default (1) can conflict with [MD012](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md012)/no-multiple-blanks, whose default value is 1. In #305 the proposed workaround was to increase MD012/no-multiple-blanks's maximum to the number of lines specified for a heading; however, that makes it impossible to prevent the occurrence of multiple blank lines in other contexts. One possible solution would be to have the values of MD022 override MD012's (similar to how in CSS more specific selectors override more generic ones); but perhaps that CSS analogy already hints at what would IMHO be a cleaner solution: since multiple blank lines around headings are a _special case_ of multiple blanks, it seems reasonable to add parameters to MD012 to allow specifying custom values in that specific context. Something like this, for example: ```yaml no-multiple-blanks: maximum: 1 headings_above: 2 headings_below: 1 ``` For prior art about rules that support parameters to apply differently in different contexts, see: - [MD013/line-length](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013), which supports the `code_blocks`, `headings` and `tables` parameters; - [MD030/list-marker-space](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md030), which supports the `ol_multi`, `ol_single`, `ul_multi` and `ul_single` parameters - [MD033/no-inline-html](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md033), which supports the `allowed_elements` parameter - and various others. I don't think we need additional parameters for other elements, but I'll mention the possibility nevertheless in case it may be considered a more consistent approach overall: this proposal of extending MD012 could subsume not just MD022, but also [MD028](https://github.com/DavidAnson/markdownlint/blob/main/doc/md028.md)/no-blanks-blockquote, [MD031](https://github.com/DavidAnson/markdownlint/blob/main/doc/md031.md)/blanks-around-fences, and [MD032](https://github.com/DavidAnson/markdownlint/blob/main/doc/md032.md)/blanks-around-lists. /cc @wedi

kerem added the

enhancement

label

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

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Sep 28, 2023):

Thinking about this very briefly, I feel like this rule should peek at any customizations applied to other built-in rules and respect them. (Although right now it does not have access to that information.) Merging some of the rules you list together does not feel right because they express different intents.

@DavidAnson commented on GitHub (Sep 28, 2023): Thinking about this very briefly, I feel like this rule should peek at any customizations applied to other built-in rules and respect them. (Although right now it does not have access to that information.) Merging some of the rules you list together does not feel right because they express different intents.

kerem commented

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

Author

Owner

@waldyrious commented on GitHub (Sep 28, 2023):

Sure — if you feel that approach makes sense, fine by me. I was under the impression that the rules were meant to be more or less independent, though, and would work consistently given the same configuration. Is there any instance of a rule's behavior being dependent on other rules' configurations?

@waldyrious commented on GitHub (Sep 28, 2023): Sure — if you feel that approach makes sense, fine by me. I was under the impression that the rules were meant to be more or less independent, though, and would work consistently given the same configuration. Is there any instance of a rule's behavior being dependent on other rules' configurations?

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Sep 28, 2023):

Rules are meant to be independent, and what I propose here would obviously not coordinate with any custom rules. There is no precedent for this, but it's the option I dislike least so far. :)

@DavidAnson commented on GitHub (Sep 28, 2023): Rules are meant to be independent, and what I propose here would obviously not coordinate with any custom rules. There is no precedent for this, but it's the option I dislike least so far. :)