feat: add frontmatterTitle option to heading-increment (#454)

* feat: add frontmatterTitle option to heading-increment

* add tests

* clarify frontmatter title as level 1 heading

* add tests for frontmatterHasTitle

Author: xbinaryx

docs/rules/heading-increment.md

@@ -25,6 +25,68 @@ Goodbye World!
 #EEE Goodbye World!
 ```
 
+## Options
+
+The following options are available on this rule:
+
+* `frontmatterTitle: string` - A regex pattern to match title fields in front matter. Front matter titles matching this pattern are treated as level 1 headings. The default pattern matches YAML (`title:`), TOML (`title =`), and JSON (`"title":`) formats. Set to an empty string to disable front matter title checking.
+
+Examples of **incorrect** code for this rule:
+
+```markdown
+<!-- eslint markdown/heading-increment: "error" -->
+
+---
+title: My Title
+---
+
+### Heading 3 with YAML front matter
+```
+
+```markdown
+<!-- eslint markdown/heading-increment: "error" -->
+
++++
+title = "My Title"
++++
+
+### Heading 3 with TOML front matter
+```
+
+```markdown
+<!-- eslint markdown/heading-increment: "error" -->
+
+---
+{ "title": "My Title" }
+---
+
+### Heading 3 with JSON front matter
+```
+
+Examples of **incorrect** code when configured as `"heading-increment": ["error", { frontmatterTitle: "\\s*heading\\s*[:=]" }]`:
+
+```markdown
+<!-- eslint markdown/heading-increment: ["error", { frontmatterTitle: "\\s*heading\\s*[:=]" }] -->
+
+---
+heading: My Title
+---
+
+### Heading 3
+```
+
+Examples of **correct** code when configured as `"heading-increment": ["error", { frontmatterTitle: "" }]`:
+
+```markdown
+<!-- eslint markdown/heading-increment: ["error", { frontmatterTitle: "" }] -->
+
+---
+title: My Title
+---
+
+### Heading 3
+```
+
 ## When Not to Use It
 
 If you aren't concerned with enforcing heading levels increment by one, you can safely disable this rule.

src/rules/heading-increment.js

@@ -3,14 +3,20 @@
  * @author Nicholas C. Zakas
  */
 
+//-----------------------------------------------------------------------------
+// Imports
+//-----------------------------------------------------------------------------
+
+import { frontmatterHasTitle } from "../util.js";
+
 //-----------------------------------------------------------------------------
 // Type Definitions
 //-----------------------------------------------------------------------------
 
 /**
  * @import { MarkdownRuleDefinition } from "../types.js";
  * @typedef {"skippedHeading"} HeadingIncrementMessageIds
- * @typedef {[]} HeadingIncrementOptions
+ * @typedef {[{ frontmatterTitle?: string }]} HeadingIncrementOptions
  * @typedef {MarkdownRuleDefinition<{ RuleOptions: HeadingIncrementOptions, MessageIds: HeadingIncrementMessageIds }>} HeadingIncrementRuleDefinition
  */
 
@@ -33,12 +39,52 @@ export default {
 			skippedHeading:
 				"Heading level skipped from {{fromLevel}} to {{toLevel}}.",
 		},
+
+		schema: [
+			{
+				type: "object",
+				properties: {
+					frontmatterTitle: {
+						type: "string",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+
+		defaultOptions: [
+			{
+				frontmatterTitle:
+					"^(?!\\s*['\"]title[:=]['\"])\\s*\\{?\\s*['\"]?title['\"]?\\s*[:=]",
+			},
+		],
 	},
 
 	create(context) {
+		const [{ frontmatterTitle }] = context.options;
+		const titlePattern =
+			frontmatterTitle === "" ? null : new RegExp(frontmatterTitle, "iu");
 		let lastHeadingDepth = 0;
 
 		return {
+			yaml(node) {
+				if (frontmatterHasTitle(node.value, titlePattern)) {
+					lastHeadingDepth = 1;
+				}
+			},
+
+			toml(node) {
+				if (frontmatterHasTitle(node.value, titlePattern)) {
+					lastHeadingDepth = 1;
+				}
+			},
+
+			json(node) {
+				if (frontmatterHasTitle(node.value, titlePattern)) {
+					lastHeadingDepth = 1;
+				}
+			},
+
 			heading(node) {
 				if (lastHeadingDepth > 0 && node.depth > lastHeadingDepth + 1) {
 					context.report({

src/rules/no-multiple-h1.js

@@ -7,7 +7,7 @@
 // Imports
 //-----------------------------------------------------------------------------
 
-import { findOffsets } from "../util.js";
+import { findOffsets, frontmatterHasTitle } from "../util.js";
 
 //-----------------------------------------------------------------------------
 // Type Definitions
@@ -26,25 +26,6 @@ import { findOffsets } from "../util.js";
 
 const h1TagPattern = /(?<!<!--[\s\S]*?)<h1[^>]*>[\s\S]*?<\/h1>/giu;
 
-/**
- * Checks if a frontmatter block contains a title matching the given pattern
- * @param {string} value The frontmatter content
- * @param {RegExp|null} pattern The pattern to match against
- * @returns {boolean} Whether a title was found
- */
-function frontmatterHasTitle(value, pattern) {
-	if (!pattern) {
-		return false;
-	}
-	const lines = value.split("\n");
-	for (const line of lines) {
-		if (pattern.test(line)) {
-			return true;
-		}
-	}
-	return false;
-}
-
 //-----------------------------------------------------------------------------
 // Rule Definition
 //-----------------------------------------------------------------------------

src/util.js

@@ -37,3 +37,22 @@ export function findOffsets(text, offset) {
 		columnOffset,
 	};
 }
+
+/**
+ * Checks if a frontmatter block contains a title matching the given pattern
+ * @param {string} value The frontmatter content
+ * @param {RegExp|null} pattern The pattern to match against
+ * @returns {boolean} Whether a title was found
+ */
+export function frontmatterHasTitle(value, pattern) {
+	if (!pattern) {
+		return false;
+	}
+	const lines = value.split("\n");
+	for (const line of lines) {
+		if (pattern.test(line)) {
+			return true;
+		}
+	}
+	return false;
+}