fix(md012): do not flag blank lines adjacent to headings (fixes #990).

Blank lines immediately above or below a heading are now excluded from
MD012's consecutive-blank-line count. Those blank lines are governed by
MD022 (blanks-around-headings), so MD012 defers to it. This means users
can set MD022's lines_above/lines_below > 1 without triggering spurious
MD012 violations.

doc-build/md012.md

@@ -19,6 +19,10 @@ Some more text here
 Note: this rule will not be triggered if there are multiple consecutive blank
 lines inside code blocks.
 
+Note: Blank lines immediately adjacent to headings are not flagged by this
+rule; the number of blank lines around headings is governed by
+`MD022`/`blanks-around-headings`.
+
 Note: The `maximum` parameter can be used to configure the maximum number of
 consecutive blank lines.
 

doc/Rules.md

@@ -470,6 +470,10 @@ Some more text here
 Note: this rule will not be triggered if there are multiple consecutive blank
 lines inside code blocks.
 
+Note: Blank lines immediately adjacent to headings are not flagged by this
+rule; the number of blank lines around headings is governed by
+`MD022`/`blanks-around-headings`.
+
 Note: The `maximum` parameter can be used to configure the maximum number of
 consecutive blank lines.
 

doc/md012.md

@@ -31,6 +31,10 @@ Some more text here
 Note: this rule will not be triggered if there are multiple consecutive blank
 lines inside code blocks.
 
+Note: Blank lines immediately adjacent to headings are not flagged by this
+rule; the number of blank lines around headings is governed by
+`MD022`/`blanks-around-headings`.
+
 Note: The `maximum` parameter can be used to configure the maximum number of
 consecutive blank lines.
 

lib/md012.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { addErrorDetailIf } from "../helpers/helpers.cjs";
+import { addErrorDetailIf, isBlankLine } from "../helpers/helpers.cjs";
 import { addRangeToSet } from "../helpers/micromark-helpers.cjs";
 import { filterByTypesCached } from "./cache.mjs";
 
@@ -17,14 +17,33 @@ export default {
     for (const codeBlock of filterByTypesCached([ "codeFenced", "codeIndented" ])) {
       addRangeToSet(codeBlockLineNumbers, codeBlock.startLine, codeBlock.endLine);
     }
+
+    // Pre-compute blank lines adjacent to headings. Heading spacing is
+    // governed by MD022 (blanks-around-headings), so MD012 defers to it
+    // and does not flag blank lines immediately above or below a heading.
+    const headingAdjacentBlanks = new Set();
+    for (const heading of filterByTypesCached([ "atxHeading", "setextHeading" ])) {
+      let i = heading.startLine - 1;
+      while (i >= 1 && isBlankLine(lines[i - 1])) {
+        headingAdjacentBlanks.add(i);
+        i--;
+      }
+      i = heading.endLine + 1;
+      while (i <= lines.length && isBlankLine(lines[i - 1])) {
+        headingAdjacentBlanks.add(i);
+        i++;
+      }
+    }
+
     let count = 0;
     for (const [ lineIndex, line ] of lines.entries()) {
-      const inCode = codeBlockLineNumbers.has(lineIndex + 1);
+      const lineNumber = lineIndex + 1;
+      const inCode = codeBlockLineNumbers.has(lineNumber);
       count = (inCode || (line.trim().length > 0)) ? 0 : count + 1;
-      if (maximum < count) {
+      if (maximum < count && !headingAdjacentBlanks.has(lineNumber)) {
         addErrorDetailIf(
           onError,
-          lineIndex + 1,
+          lineNumber,
           maximum,
           count,
           undefined,

test/no-multiple-blanks-headings.md

@@ -0,0 +1,23 @@
+# Heading
+
+
+## Two blank lines above
+
+Content.
+
+
+## Two blank lines above again
+
+More content.
+
+Text
+
+
+Text {MD012:15}
+
+Text
+
+
+## Three blank lines above
+
+Text

test/snapshots/markdownlint-test-scenarios.mjs.md

@@ -46267,6 +46267,54 @@ Generated by [AVA](https://avajs.dev).
       `,
     }
 
+## no-multiple-blanks-headings.md
+
+> Snapshot 1
+
+    {
+      errors: [
+        {
+          errorContext: null,
+          errorDetail: 'Expected: 1; Actual: 2',
+          errorRange: null,
+          fixInfo: {
+            deleteCount: -1,
+          },
+          lineNumber: 15,
+          ruleDescription: 'Multiple consecutive blank lines',
+          ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md012.md',
+          ruleNames: [
+            'MD012',
+            'no-multiple-blanks',
+          ],
+          severity: 'error',
+        },
+      ],
+      fixed: `# Heading␊
+      ␊
+      ␊
+      ## Two blank lines above␊
+      ␊
+      Content.␊
+      ␊
+      ␊
+      ## Two blank lines above again␊
+      ␊
+      More content.␊
+      ␊
+      Text␊
+      ␊
+      Text {MD012:15}␊
+      ␊
+      Text␊
+      ␊
+      ␊
+      ## Three blank lines above␊
+      ␊
+      Text␊
+      `,
+    }
+
 ## no-multiple-blanks-maximum.md
 
 > Snapshot 1