starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 09:16:02 +03:00

[GH-ISSUE #305] [MD012] Allow/enforce multiple blank lines before heading to add visual gaps #2109

New issue

Closed

opened 2026-03-07 20:04:39 +03:00 by kerem · 8 comments

kerem commented

2026-03-07 20:04:39 +03:00

Owner

Originally created by @wedi on GitHub (Jul 12, 2020).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/305

Hi,

it would be cool if there were a configuration option that allows (to enforce) more than one blank line before a heading.

Reasoning: If you rarely read the rendered version of a Markdown file but often look into the source, either to make modifications or to find some information in a cloned project, it would be of much help to have some visual gaps between sections. Just like the differently sized margins in a rendered document. Personally, I think this makes it much easier to find what you look for, especially in longer documents.

Overengineered version:

Allow/enforce multiple blank lines only if the previous non blank line is not a heading.
Allow/enforce different settings in different nesting levels.

I looked into the MD012 function to do the allow part but I haven't found a way to determine if the current line contains a heading. I guess you need to check token.type of the first token in the line but how do you get that token? Or would you need to extend the (a bit cryptic) getLineMetadata function along the lines of inBreak and onFence?

Originally created by @wedi on GitHub (Jul 12, 2020). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/305 Hi, it would be cool if there were a configuration option that allows (to enforce) more than one blank line before a heading. Reasoning: If you rarely read the rendered version of a Markdown file but often look into the source, either to make modifications or to find some information in a cloned project, it would be of much help to have some visual gaps between sections. Just like the differently sized margins in a rendered document. Personally, I think this makes it much easier to find what you look for, especially in longer documents. Overengineered version: - Allow/enforce multiple blank lines only if the previous non blank line is not a heading. - Allow/enforce different settings in different nesting levels. I looked into the `MD012` function to do the allow part but I haven't found a way to determine if the current line contains a heading. I guess you need to check `token.type` of the first token in the line but how do you get that token? Or would you need to extend the (a bit cryptic) `getLineMetadata` function along the lines of `inBreak` and `onFence`?

kerem

2026-03-07 20:04:39 +03:00

closed this issue
added the
new rule
label

kerem commented

2026-03-07 20:04:40 +03:00

Author

Owner

@younger-1 commented on GitHub (Jul 27, 2020):

With such rule, it will be very nice to read rendered MD files. 😄

@younger-1 commented on GitHub (Jul 27, 2020): With such rule, it will be very nice to read rendered MD files. 😄

kerem commented

2026-03-07 20:04:40 +03:00

Author

Owner

@younger-1 commented on GitHub (Jul 28, 2020):

Surprise! 😺 There are other solution to get this down.

https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md022
https://github.com/DavidAnson/markdownlint/issues/143

With Rule MD022, you can add random number of empty lines above or below headings.

In short, you can add this to your setting.json :

{
    "markdownlint.config": {
        "MD012": {
            "maximum": 3
        },
        "MD022": {
            "lines_above": 3,
            "lines_below": 1
        },
    },
}

@younger-1 commented on GitHub (Jul 28, 2020): Surprise! 😺 There are other solution to get this down. > https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md022 > https://github.com/DavidAnson/markdownlint/issues/143 With Rule **MD022**, you can add random number of empty lines above or below headings. In short, you can add this to your `setting.json` : ```json { "markdownlint.config": { "MD012": { "maximum": 3 }, "MD022": { "lines_above": 3, "lines_below": 1 }, }, } ```

kerem commented

2026-03-07 20:04:40 +03:00

Author

Owner

@younger-1 commented on GitHub (Jul 28, 2020):

By the way, I wonder if there is a way to precisely control the number of blank lines of different headings.

Like this: I want the <h1/h2/h3> headings with 6 blank lines before them and the <h4/h5/h6> headings with 3 blank lines before them.

So after rendering MD files, the 'Biger' headings can have more line before them. This can be helpful to look through the files

@younger-1 commented on GitHub (Jul 28, 2020): By the way, I wonder if there is a way to precisely control the number of blank lines of different headings. Like this: I want the <h1/h2/h3> headings with 6 blank lines before them and the <h4/h5/h6> headings with 3 blank lines before them. So after rendering MD files, the 'Biger' headings can have more line before them. This can be helpful to look through the files

kerem commented

2026-03-07 20:04:40 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 28, 2020):

Yes, thanks @younger-1, what you show with https://github.com/DavidAnson/markdownlint/issues/305#issuecomment-664735479 is what @wedi was asking for. I will close this issue.

Your question at https://github.com/DavidAnson/markdownlint/issues/305#issuecomment-664739001 is not currently supported, but could be an enhancement.

@DavidAnson commented on GitHub (Jul 28, 2020): Yes, thanks @younger-1, what you show with https://github.com/DavidAnson/markdownlint/issues/305#issuecomment-664735479 is what @wedi was asking for. I will close this issue. Your question at https://github.com/DavidAnson/markdownlint/issues/305#issuecomment-664739001 is not currently supported, but could be an enhancement.

kerem commented

2026-03-07 20:04:40 +03:00

Author

Owner

@younger-1 commented on GitHub (Jul 28, 2020):

@DavidAnson Oh, yes! Thank you for your great work!

@younger-1 commented on GitHub (Jul 28, 2020): @DavidAnson Oh, yes! Thank you for your great work!

kerem commented

2026-03-07 20:04:40 +03:00

Author

Owner

@wedi commented on GitHub (Jul 28, 2020):

Thanks for pointing this out, @younger-1! This reminds me that I already stumbled upon this issue quite some time ago and saw this myself back then. 🤗

But since I have already opened this ticket, I'd like to ask if it might be reasonable to merge MD012 and MD022 into one rule caring about blank lines everywhere. This would work around the limitation that you cannot have less blank lines allowed in MD012 as you set in MD022 (mentioned in https://github.com/DavidAnson/markdownlint/issues/143#issuecomment-478334254). This would also be the place to implement the suggestion above to have different spaces between different heading levels (https://github.com/DavidAnson/markdownlint/issues/305#issuecomment-664739001).

@wedi commented on GitHub (Jul 28, 2020): Thanks for pointing this out, @younger-1! This reminds me that I already stumbled upon this issue quite some time ago and saw this myself back then. 🤗 But since I have already opened this ticket, I'd like to ask if it might be reasonable to merge MD012 and MD022 into one rule caring about blank lines everywhere. This would work around the limitation that you cannot have less blank lines allowed in MD012 as you set in MD022 (mentioned in https://github.com/DavidAnson/markdownlint/issues/143#issuecomment-478334254). This would also be the place to implement the suggestion above to have different spaces between different heading levels (https://github.com/DavidAnson/markdownlint/issues/305#issuecomment-664739001).

kerem commented

2026-03-07 20:04:40 +03:00

Author

Owner

@waldyrious commented on GitHub (Aug 1, 2020):

Yes, thanks @younger-1, what you show with https://github.com/DavidAnson/markdownlint/issues/305#issuecomment-664735479 is what @wedi was asking for. I will close this issue.

I'm with @wedi here — requiring an increase of MD012/no-multiple-blanks's maximum to allow multiple lines above a heading also makes it impossible to require no multiple blank lines in other contexts, so IMO this issue should not be closed as the current workaround has drawbacks.

A somewhat backward-compatible fix could be to simply make the values of MD022/blanks-around-headers override MD012's, but I agree that a cleaner solution would be to have a single rule for blank lines.

@waldyrious commented on GitHub (Aug 1, 2020): > Yes, thanks `@younger-1`, what you show with https://github.com/DavidAnson/markdownlint/issues/305#issuecomment-664735479 is what `@wedi` was asking for. I will close this issue. I'm with @wedi here — requiring an increase of `MD012`/`no-multiple-blanks`'s `maximum` to allow multiple lines above a heading also makes it impossible to require no multiple blank lines in other contexts, so IMO this issue should not be closed as the current workaround has drawbacks. A somewhat backward-compatible fix could be to simply make the values of `MD022`/`blanks-around-headers` override MD012's, but I agree that a cleaner solution would be to have a single rule for blank lines.

kerem commented

2026-03-07 20:04:40 +03:00

Author

Owner

@DavidAnson commented on GitHub (Aug 1, 2020):

@waldyrious @wedi I understand what you are both saying. I intend to close this issue because it has been addressed. If you’d like to open a new issue for merging those two rules, I will leave that open and label it accordingly. Thank you!

@DavidAnson commented on GitHub (Aug 1, 2020): @waldyrious @wedi I understand what you are both saying. I intend to close this issue because it has been addressed. If you’d like to open a new issue for merging those two rules, I will leave that open and label it accordingly. Thank you!