MD001/heading-increment: Support front matter title as the first heading of the page (fixes #1613).

doc-build/md001.md

@@ -26,6 +26,15 @@ level at a time:
 ### Another Heading 3
 ```
 
+If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+contains a `title` property (commonly used with blog posts), this rule treats
+that as a top level heading and will report a violation if the actual first
+heading is not a level 2 heading. To use a different property name in the
+front matter, specify the text of a regular expression via the
+`front_matter_title` parameter. To disable the use of front matter by this
+rule, specify `""` for `front_matter_title`. When front matter is not present,
+the first heading can be any level.
+
 Rationale: Headings represent the structure of a document and can be confusing
 when skipped - especially for accessibility scenarios. More information:
 <https://www.w3.org/WAI/tutorials/page-structure/headings/>.

doc/Rules.md

@@ -12,6 +12,11 @@ Tags: `headings`
 
 Aliases: `heading-increment`
 
+Parameters:
+
+- `front_matter_title`: RegExp for matching title in front matter (`string`,
+  default `^\s*title\s*[:=]`)
+
 This rule is triggered when you skip heading levels in a Markdown document, for
 example:
 
@@ -40,6 +45,15 @@ level at a time:
 ### Another Heading 3
 ```
 
+If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+contains a `title` property (commonly used with blog posts), this rule treats
+that as a top level heading and will report a violation if the actual first
+heading is not a level 2 heading. To use a different property name in the
+front matter, specify the text of a regular expression via the
+`front_matter_title` parameter. To disable the use of front matter by this
+rule, specify `""` for `front_matter_title`. When front matter is not present,
+the first heading can be any level.
+
 Rationale: Headings represent the structure of a document and can be confusing
 when skipped - especially for accessibility scenarios. More information:
 <https://www.w3.org/WAI/tutorials/page-structure/headings/>.

doc/md001.md

@@ -4,6 +4,11 @@ Tags: `headings`
 
 Aliases: `heading-increment`
 
+Parameters:
+
+- `front_matter_title`: RegExp for matching title in front matter (`string`,
+  default `^\s*title\s*[:=]`)
+
 This rule is triggered when you skip heading levels in a Markdown document, for
 example:
 
@@ -32,6 +37,15 @@ level at a time:
 ### Another Heading 3
 ```
 
+If [YAML](https://en.wikipedia.org/wiki/YAML) front matter is present and
+contains a `title` property (commonly used with blog posts), this rule treats
+that as a top level heading and will report a violation if the actual first
+heading is not a level 2 heading. To use a different property name in the
+front matter, specify the text of a regular expression via the
+`front_matter_title` parameter. To disable the use of front matter by this
+rule, specify `""` for `front_matter_title`. When front matter is not present,
+the first heading can be any level.
+
 Rationale: Headings represent the structure of a document and can be confusing
 when skipped - especially for accessibility scenarios. More information:
 <https://www.w3.org/WAI/tutorials/page-structure/headings/>.

lib/configuration-strict.d.ts

@@ -21,11 +21,25 @@ export interface ConfigurationStrict {
   /**
    * MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md
    */
-  MD001?: boolean;
+  MD001?:
+    | boolean
+    | {
+        /**
+         * RegExp for matching title in front matter
+         */
+        front_matter_title?: string;
+      };
   /**
    * MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md
    */
-  "heading-increment"?: boolean;
+  "heading-increment"?:
+    | boolean
+    | {
+        /**
+         * RegExp for matching title in front matter
+         */
+        front_matter_title?: string;
+      };
   /**
    * MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md003.md
    */

lib/md001.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { addErrorDetailIf } from "../helpers/helpers.cjs";
+import { addErrorDetailIf, frontMatterHasTitle } from "../helpers/helpers.cjs";
 import { getHeadingLevel } from "../helpers/micromark-helpers.cjs";
 import { filterByTypesCached } from "./cache.mjs";
 
@@ -11,7 +11,11 @@ export default {
   "tags": [ "headings" ],
   "parser": "micromark",
   "function": function MD001(params, onError) {
-    let prevLevel = Number.MAX_SAFE_INTEGER;
+    const hasTitle = frontMatterHasTitle(
+      params.frontMatterLines,
+      params.config.front_matter_title
+    );
+    let prevLevel = hasTitle ? 1 : Number.MAX_SAFE_INTEGER;
     for (const heading of filterByTypesCached([ "atxHeading", "setextHeading" ])) {
       const level = getHeadingLevel(heading);
       if (level > prevLevel) {

schema/.markdownlint.jsonc

@@ -8,7 +8,10 @@
   "extends": null,
 
   // MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md
-  "MD001": true,
+  "MD001": {
+    // RegExp for matching title in front matter
+    "front_matter_title": "^\\s*title\\s*[:=]"
+  },
 
   // MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md003.md
   "MD003": {

schema/.markdownlint.yaml

@@ -7,7 +7,9 @@ default: true
 extends: null
 
 # MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md
-MD001: true
+MD001:
+  # RegExp for matching title in front matter
+  front_matter_title: "^\\s*title\\s*[:=]"
 
 # MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md003.md
 MD003:

schema/build-config-schema.mjs

@@ -64,6 +64,15 @@ for (const rule of rules) {
   };
   let custom = true;
   switch (ruleName) {
+    case "MD001":
+      scheme.properties = {
+        "front_matter_title": {
+          "description": "RegExp for matching title in front matter",
+          "type": "string",
+          "default": "^\\s*title\\s*[:=]"
+        }
+      };
+      break;
     case "MD003":
       scheme.properties = {
         "style": {

schema/markdownlint-config-schema-strict.json

@@ -24,13 +24,35 @@
     },
     "MD001": {
       "description": "MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md",
-      "type": "boolean",
+      "type": [
-      "default": true
+        "boolean",
+        "object"
+      ],
+      "default": true,
+      "properties": {
+        "front_matter_title": {
+          "description": "RegExp for matching title in front matter",
+          "type": "string",
+          "default": "^\\s*title\\s*[:=]"
+        }
+      },
+      "additionalProperties": false
     },
     "heading-increment": {
       "description": "MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md",
-      "type": "boolean",
+      "type": [
-      "default": true
+        "boolean",
+        "object"
+      ],
+      "default": true,
+      "properties": {
+        "front_matter_title": {
+          "description": "RegExp for matching title in front matter",
+          "type": "string",
+          "default": "^\\s*title\\s*[:=]"
+        }
+      },
+      "additionalProperties": false
     },
     "MD003": {
       "description": "MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md003.md",

schema/markdownlint-config-schema.json

@@ -24,13 +24,35 @@
     },
     "MD001": {
       "description": "MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md",
-      "type": "boolean",
+      "type": [
-      "default": true
+        "boolean",
+        "object"
+      ],
+      "default": true,
+      "properties": {
+        "front_matter_title": {
+          "description": "RegExp for matching title in front matter",
+          "type": "string",
+          "default": "^\\s*title\\s*[:=]"
+        }
+      },
+      "additionalProperties": false
     },
     "heading-increment": {
       "description": "MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md",
-      "type": "boolean",
+      "type": [
-      "default": true
+        "boolean",
+        "object"
+      ],
+      "default": true,
+      "properties": {
+        "front_matter_title": {
+          "description": "RegExp for matching title in front matter",
+          "type": "string",
+          "default": "^\\s*title\\s*[:=]"
+        }
+      },
+      "additionalProperties": false
     },
     "MD003": {
       "description": "MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md003.md",

test/heading_increment-alt_title_level3_bad.md

@@ -0,0 +1,14 @@
+---
+alternate = heading_increment-alt_title_level3_bad
+---
+
+### level 3 {MD001}
+
+<!-- markdownlint-configure-file {
+  "heading-increment": {
+    "front_matter_title": "^\\s*alternate\\s*="
+  },
+  "first-line-heading": {
+    "front_matter_title": "^\\s*alternate\\s*="
+  }
+} -->

test/heading_increment-title_level2_good.md

@@ -0,0 +1,7 @@
+---
+title: heading_increment-title_level2_good
+---
+
+## level 2
+
+### level 3

test/heading_increment-title_level3_bad.md

@@ -0,0 +1,5 @@
+---
+title: heading_increment-title_level3_good
+---
+
+### level 3 {MD001}

test/markdownlint-test.mjs

@@ -908,7 +908,7 @@ test("readme", async(t) => {
 });
 
 test("validateJsonUsingConfigSchemaStrict", async(t) => {
-  t.plan(203);
+  t.plan(204);
   // @ts-ignore
   const ajv = new Ajv(ajvOptions);
   const validateSchemaStrict = ajv.compile(configSchemaStrict);

test/snapshots/markdownlint-test-repos-mdn-content.mjs.md

@@ -8,4 +8,81 @@ Generated by [AVA](https://avajs.dev).
 
 > Expected linting violations
 
-    ''
+    `test-repos/mdn-content/files/en-us/glossary/denial_of_service/index.md: 15: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/flex/index.md: 15: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/function/index.md: 13: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/https_rr/index.md: 14: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/intrinsic_size/index.md: 21: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h4]␊
+    test-repos/mdn-content/files/en-us/glossary/parameter/index.md: 32: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/prefetch/index.md: 13: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/session_hijacking/index.md: 15: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/time_to_interactive/index.md: 13: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h4]␊
+    test-repos/mdn-content/files/en-us/glossary/truthy/index.md: 31: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/xhtml/index.md: 13: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/glossary/xlink/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/learn_web_development/howto/solve_html_problems/index.md: 11: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/add-ons/contact_us/index.md: 11: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/add-ons/webextensions/manifest.json/externally_connectable/index.md: 54: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/add-ons/webextensions/manifest.json/host_permissions/index.md: 40: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/firefox/releases/1.5/what_s_new_in_1.5_alpha/index.md: 11: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/firefox/releases/3/dom_improvements/index.md: 21: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/firefox/releases/3/full_page_zoom/index.md: 11: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/firefox/releases/3/notable_bugs_fixed/index.md: 27: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/firefox/releases/3/templates/index.md: 11: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/mozilla/firefox/releases/3/xul_improvements_in_firefox_3/index.md: 11: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/accessibility/aria/how_to/file_aria-related_bugs/index.md: 10: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/canvasrenderingcontext2d/save/index.md: 16: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/delegatedinktrailpresenter/expectedimprovement/index.md: 16: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/delegatedinktrailpresenter/presentationarea/index.md: 19: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/editcontext/updatecharacterbounds/index.md: 19: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/fetchevent/respondwith/index.md: 30: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/htmlelement/dataset/index.md: 40: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/htmlelement/editcontext/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/reportbody/index.md: 12: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatepairstats/bytesdiscardedonsend/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatepairstats/consentrequestssent/index.md: 19: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatepairstats/packetsdiscardedonsend/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatepairstats/packetsreceived/index.md: 15: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatepairstats/packetssent/index.md: 15: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatestats/candidatetype/index.md: 13: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatestats/foundation/index.md: 19: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatestats/priority/index.md: 13: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcicecandidatestats/usernamefragment/index.md: 19: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcrtpreceiver/transform/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/rtcrtpsender/transform/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/texttrack/mode/index.md: 21: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/api/webrtc_api/build_a_phone_with_peerjs/index.md: 15: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/css_animations/index.md: 14: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/css_backgrounds_and_borders/index.md: 20: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/css_basic_user_interface/index.md: 14: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/css_colors/index.md: 16: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/css_compositing_and_blending/index.md: 16: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/css_filter_effects/index.md: 14: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/css_generated_content/index.md: 14: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/css_selectors/selector_structure/index.md: 14: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/css/font-variant-caps/index.md: 55: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/html/reference/attributes/crossorigin/index.md: 64: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/html/reference/attributes/maxlength/index.md: 19: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/html/reference/attributes/required/index.md: 27: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/html/reference/elements/input/range/index.md: 52: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/html/reference/elements/input/time/index.md: 44: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/html/reference/elements/meta/name/index.md: 12: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/html/reference/global_attributes/data-_star_/index.md: 74: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/html/reference/global_attributes/itemscope/index.md: 20: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/progressive_web_apps/manifest/reference/display_override/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/progressive_web_apps/manifest/reference/file_handlers/index.md: 22: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/progressive_web_apps/manifest/reference/launch_handler/index.md: 15: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/progressive_web_apps/manifest/reference/note_taking/index.md: 15: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/progressive_web_apps/manifest/reference/protocol_handlers/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/progressive_web_apps/manifest/reference/serviceworker/index.md: 16: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/progressive_web_apps/manifest/reference/share_target/index.md: 20: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/progressive_web_apps/tutorials/js13kgames/app_structure/index.md: 17: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/svg/guides/namespaces_crash_course/index.md: 10: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/svg/guides/scripting/index.md: 13: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/svg/tutorials/svg_from_scratch/other_content_in_svg/index.md: 12: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/webdriver/reference/capabilities/firefoxoptions/index.md: 18: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h5]␊
+    test-repos/mdn-content/files/en-us/web/xml/xpath/guides/snippets/index.md: 10: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/xml/xslt/guides/common_errors/index.md: 8: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/xml/xslt/guides/pi_parameters/index.md: 8: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/web/xml/xslt/reference/element/stylesheet/index.md: 10: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/mdn-content/files/en-us/webassembly/guides/existing_c_to_wasm/index.md: 66: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]`

test/snapshots/markdownlint-test-repos-small.mjs.md

@@ -315,6 +315,8 @@ Generated by [AVA](https://avajs.dev).
     test-repos/pi-hole-docs/docs/guides/vpn/openvpn/clients.md: 38: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊
     test-repos/pi-hole-docs/docs/guides/vpn/openvpn/dual-operation.md: 5: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊
     test-repos/pi-hole-docs/docs/guides/vpn/openvpn/firewall.md: 61: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊
+    test-repos/pi-hole-docs/docs/main/coverage.md: 7: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
+    test-repos/pi-hole-docs/docs/main/prerequisites.md: 7: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
     test-repos/pi-hole-docs/docs/main/prerequisites.md: 15: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]`
 
 ## https://github.com/v8/v8.dev
@@ -326,10 +328,12 @@ Generated by [AVA](https://avajs.dev).
     test-repos/v8-v8-dev/src/blog/adaptor-frame.md: 89: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊
     test-repos/v8-v8-dev/src/blog/adaptor-frame.md: 232: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊
     test-repos/v8-v8-dev/src/blog/explicit-compile-hints.md: 22: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊
+    test-repos/v8-v8-dev/src/blog/extras/understanding-ecmascript-part-2-extra.md: 13: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
     test-repos/v8-v8-dev/src/blog/fast-for-in.md: 271: MD058/blanks-around-tables Tables should be surrounded by blank lines [Context: "| Internal method       | Hand..."]␊
     test-repos/v8-v8-dev/src/blog/fast-for-in.md: 277: MD058/blanks-around-tables Tables should be surrounded by blank lines [Context: "| \`[[OwnPropertyKeys]]\` | \`own..."]␊
     test-repos/v8-v8-dev/src/blog/fast-for-in.md: 351: MD058/blanks-around-tables Tables should be surrounded by blank lines [Context: "| Position | Name             ..."]␊
     test-repos/v8-v8-dev/src/blog/fast-for-in.md: 369: MD058/blanks-around-tables Tables should be surrounded by blank lines [Context: "| 17       | \`ForInFilter\`    ..."]␊
+    test-repos/v8-v8-dev/src/blog/fast-super.md: 27: MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]␊
     test-repos/v8-v8-dev/src/blog/high-performance-cpp-gc.md: 29: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊
     test-repos/v8-v8-dev/src/blog/jspi-ot.md: 13: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊
     test-repos/v8-v8-dev/src/blog/jspi-ot.md: 13: MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]␊

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

@@ -16178,6 +16178,87 @@ Generated by [AVA](https://avajs.dev).
       `,
     }
 
+## heading_increment-alt_title_level3_bad.md
+
+> Snapshot 1
+
+    {
+      errors: [
+        {
+          errorContext: null,
+          errorDetail: 'Expected: h2; Actual: h3',
+          errorRange: null,
+          fixInfo: null,
+          lineNumber: 5,
+          ruleDescription: 'Heading levels should only increment by one level at a time',
+          ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md001.md',
+          ruleNames: [
+            'MD001',
+            'heading-increment',
+          ],
+        },
+      ],
+      fixed: `---␊
+      alternate = heading_increment-alt_title_level3_bad␊
+      ---␊
+      ␊
+      ### level 3 {MD001}␊
+      ␊
+      <!-- markdownlint-configure-file {␊
+        "heading-increment": {␊
+          "front_matter_title": "^\\\\s*alternate\\\\s*="␊
+        },␊
+        "first-line-heading": {␊
+          "front_matter_title": "^\\\\s*alternate\\\\s*="␊
+        }␊
+      } -->␊
+      `,
+    }
+
+## heading_increment-title_level2_good.md
+
+> Snapshot 1
+
+    {
+      errors: [],
+      fixed: `---␊
+      title: heading_increment-title_level2_good␊
+      ---␊
+      ␊
+      ## level 2␊
+      ␊
+      ### level 3␊
+      `,
+    }
+
+## heading_increment-title_level3_bad.md
+
+> Snapshot 1
+
+    {
+      errors: [
+        {
+          errorContext: null,
+          errorDetail: 'Expected: h2; Actual: h3',
+          errorRange: null,
+          fixInfo: null,
+          lineNumber: 5,
+          ruleDescription: 'Heading levels should only increment by one level at a time',
+          ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md001.md',
+          ruleNames: [
+            'MD001',
+            'heading-increment',
+          ],
+        },
+      ],
+      fixed: `---␊
+      title: heading_increment-title_level3_good␊
+      ---␊
+      ␊
+      ### level 3 {MD001}␊
+      `,
+    }
+
 ## heading_multiple_toplevel.md
 
 > Snapshot 1