[GH-ISSUE #786] MD022: Custom space between headers #530

New issue

Closed

opened 2026-03-03 01:27:43 +03:00 by kerem · 2 comments

kerem commented

2026-03-03 01:27:43 +03:00

Owner

Originally created by @st-pasha on GitHub (Apr 21, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/786

I'm currently using the following configuration for rule MD022:

MD022:
  lines_above: 2
  lines_below: 1

Which works nicely, except in situations when an H1 header is immediately followed by an H2 header. Here's an example of a document (the way I'd like it to be formatted):

# Page title

## First section

Fusce bibendum, mauris vitae ultrices aliquet, nulla enim porttitor elit, a luctus tellus felis
vel velit. Donec eget odio eu nulla pharetra ultrices. Proin bibendum eleifend ante, vel 
aliquam sapien vehicula nec. Nulla facilisi. 

Sed at mi sit amet libero porttitor dignissim. Vestibulum rutrum sem eu quam venenatis, a 
elementum ex vestibulum. 


## Second section

Sed at tortor eu nisl pharetra blandit eget in dolor. Sed rutrum urna mauris, ac hendrerit nisl 
iaculis at. Sed tristique, libero eu malesuada luctus, nunc lacus ultricies ex, eget iaculis 
quam enim vitae purus. Integer eget velit vitae velit posuere hendrerit. Etiam eleifend purus 
vitae urna lacinia interdum. Sed semper, turpis a venenatis consequat, sapien sapien vehicula 
nisi, nec iaculis arcu ex sit amet sapien. Donec posuere finibus velit.

but instead, rule MD022 forces 2 spaces between the # Page title and ## First section.

So, what I'd like to propose is to introduce a new parameter into the rule MD022, which could perhaps be called lines_between, and this parameter, if present, will specify the number of blank lines to insert between a header of level N and a header of level N+1 if it immediately follows.

Rationale: two blank lines are useful to clearly separate one section of text from another (a single line is insufficient because then it looks like a regular paragraph break). However, when a header is immediately followed by a sub-header, then there is no "preceding section", and extra whitespace is unnecessary and looks jarring.

Originally created by @st-pasha on GitHub (Apr 21, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/786 I'm currently using the following configuration for rule MD022: ``` MD022: lines_above: 2 lines_below: 1 ``` Which works nicely, except in situations when an H1 header is immediately followed by an H2 header. Here's an example of a document (the way I'd like it to be formatted): ``` # Page title ## First section Fusce bibendum, mauris vitae ultrices aliquet, nulla enim porttitor elit, a luctus tellus felis vel velit. Donec eget odio eu nulla pharetra ultrices. Proin bibendum eleifend ante, vel aliquam sapien vehicula nec. Nulla facilisi. Sed at mi sit amet libero porttitor dignissim. Vestibulum rutrum sem eu quam venenatis, a elementum ex vestibulum. ## Second section Sed at tortor eu nisl pharetra blandit eget in dolor. Sed rutrum urna mauris, ac hendrerit nisl iaculis at. Sed tristique, libero eu malesuada luctus, nunc lacus ultricies ex, eget iaculis quam enim vitae purus. Integer eget velit vitae velit posuere hendrerit. Etiam eleifend purus vitae urna lacinia interdum. Sed semper, turpis a venenatis consequat, sapien sapien vehicula nisi, nec iaculis arcu ex sit amet sapien. Donec posuere finibus velit. ``` but instead, rule **MD022** forces 2 spaces between the `# Page title` and `## First section`. So, what I'd like to propose is to introduce a new parameter into the rule MD022, which could perhaps be called `lines_between`, and this parameter, if present, will specify the number of blank lines to insert between a header of level `N` and a header of level `N+1` if it immediately follows. Rationale: two blank lines are useful to clearly separate one section of text from another (a single line is insufficient because then it looks like a regular paragraph break). However, when a header is immediately followed by a sub-header, then there is no "preceding section", and extra whitespace is unnecessary and looks jarring.