feat: add no-multiple-h1 rule (#377)

* feat: add no-multiple-h1 rule

* add a test where the heading is inside of a code block

* support front matter titles

* review comments

* review comments

* review comments

* review comments

Author: Pixel998

README.md

@@ -84,6 +84,7 @@ export default defineConfig([
 | [`no-invalid-label-refs`](./docs/rules/no-invalid-label-refs.md) | Disallow invalid label references | yes |
 | [`no-missing-atx-heading-space`](./docs/rules/no-missing-atx-heading-space.md) | Disallow headings without a space after the hash characters | yes |
 | [`no-missing-label-refs`](./docs/rules/no-missing-label-refs.md) | Disallow missing label references | yes |
+| [`no-multiple-h1`](./docs/rules/no-multiple-h1.md) | Disallow multiple H1 headings in the same document | yes |
 | [`require-alt-text`](./docs/rules/require-alt-text.md) | Require alternative text for images | yes |
 <!-- Rule Table End -->
 

docs/rules/no-multiple-h1.md

@@ -0,0 +1,93 @@
+# no-multiple-h1
+
+Disallow multiple H1 headings in the same document.
+
+## Background
+
+An H1 heading is meant to define the main heading of a page, providing important structural information for both users and assistive technologies. Using more than one H1 heading per page can cause confusion for screen readers, dilute SEO signals, and break the logical content hierarchy. While modern search engines are more forgiving, best practice is to use a single H1 heading to ensure clarity and accessibility.
+
+## Rule Details
+
+This rule warns when it finds more than one H1 heading in a Markdown document. It checks for:
+
+- ATX-style headings (`# Heading`)
+- Setext-style headings (`Heading\n=========`)
+- Front matter title fields (YAML and TOML)
+- HTML h1 tags (`<h1>Heading</h1>`)
+
+Examples of **incorrect** code for this rule:
+
+```markdown
+<!-- eslint markdown/no-multiple-h1: "error" -->
+
+# Heading 1
+
+# Another H1 heading
+```
+
+```markdown
+<!-- eslint markdown/no-multiple-h1: "error" -->
+
+# Heading 1
+
+Another H1 heading
+==================
+```
+
+```markdown
+<!-- eslint markdown/no-multiple-h1: "error" -->
+
+<h1>First Heading</h1>
+
+<h1>Second Heading</h1>
+```
+
+## Options
+
+The following options are available on this rule:
+
+* `frontmatterTitle: string` - A regex pattern to match title fields in front matter. The default pattern matches both YAML (`title:`) and TOML (`title =`) formats. Set to an empty string to disable front matter title checking.
+
+Examples of **incorrect** code for this rule:
+
+```markdown
+<!-- eslint markdown/no-multiple-h1: "error" -->
+
+---
+title: My Title
+---
+
+# Heading 1
+```
+
+Examples of **incorrect** code when configured as `"no-multiple-h1": ["error", { "frontmatterTitle": "\\s*heading\\s*[:=]" }]`:
+
+```markdown
+<!-- eslint markdown/no-multiple-h1: ["error", { "frontmatterTitle": "\\s*heading\\s*[:=]" }] -->
+
+---
+heading: My Title
+---
+
+# Heading 1
+```
+
+Examples of **correct** code when configured as `"no-multiple-h1": ["error", { "frontmatterTitle": "" }]`:
+
+```markdown
+<!-- eslint markdown/no-multiple-h1: ["error", { frontmatterTitle: "" }] -->
+
+---
+title: My Title
+---
+
+# Heading 1
+```
+
+## When Not to Use It
+
+If you have a specific use case that requires multiple H1 headings in a single Markdown document, you can safely disable this rule. However, this is not recommended.
+
+## Prior Art
+
+* [MD025 - Multiple top-level headings in the same document](https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md)

src/rules/no-multiple-h1.js

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Rule to enforce at most one H1 heading in Markdown.
+ * @author Pixel998
+ */
+
+//-----------------------------------------------------------------------------
+// Imports
+//-----------------------------------------------------------------------------
+
+import { findOffsets } from "../util.js";
+
+//-----------------------------------------------------------------------------
+// Type Definitions
+//-----------------------------------------------------------------------------
+
+/**
+ * @typedef {import("../types.ts").MarkdownRuleDefinition<{ RuleOptions: [{ frontmatterTitle?: string; }]; }>}
+ * NoMultipleH1RuleDefinition
+ */
+
+//-----------------------------------------------------------------------------
+// Helpers
+//-----------------------------------------------------------------------------
+
+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
+//-----------------------------------------------------------------------------
+
+/** @type {NoMultipleH1RuleDefinition} */
+export default {
+	meta: {
+		type: "problem",
+
+		docs: {
+			recommended: true,
+			description: "Disallow multiple H1 headings in the same document",
+			url: "https://github.com/eslint/markdown/blob/main/docs/rules/no-multiple-h1.md",
+		},
+
+		messages: {
+			multipleH1: "Unexpected additional H1 heading found.",
+		},
+
+		schema: [
+			{
+				type: "object",
+				properties: {
+					frontmatterTitle: {
+						type: "string",
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+
+		defaultOptions: [
+			{ frontmatterTitle: "^\\s*['\"]?title['\"]?\\s*[:=]" },
+		],
+	},
+
+	create(context) {
+		const [{ frontmatterTitle }] = context.options;
+		const titlePattern =
+			frontmatterTitle === "" ? null : new RegExp(frontmatterTitle, "iu");
+		let h1Count = 0;
+
+		return {
+			yaml(node) {
+				if (frontmatterHasTitle(node.value, titlePattern)) {
+					h1Count++;
+				}
+			},
+
+			toml(node) {
+				if (frontmatterHasTitle(node.value, titlePattern)) {
+					h1Count++;
+				}
+			},
+
+			html(node) {
+				let match;
+				while ((match = h1TagPattern.exec(node.value)) !== null) {
+					h1Count++;
+					if (h1Count > 1) {
+						const {
+							lineOffset: startLineOffset,
+							columnOffset: startColumnOffset,
+						} = findOffsets(node.value, match.index);
+
+						const {
+							lineOffset: endLineOffset,
+							columnOffset: endColumnOffset,
+						} = findOffsets(
+							node.value,
+							match.index + match[0].length,
+						);
+
+						const nodeStartLine = node.position.start.line;
+						const nodeStartColumn = node.position.start.column;
+						const startLine = nodeStartLine + startLineOffset;
+						const endLine = nodeStartLine + endLineOffset;
+						const startColumn =
+							(startLine === nodeStartLine
+								? nodeStartColumn
+								: 1) + startColumnOffset;
+						const endColumn =
+							(endLine === nodeStartLine ? nodeStartColumn : 1) +
+							endColumnOffset;
+
+						context.report({
+							loc: {
+								start: {
+									line: startLine,
+									column: startColumn,
+								},
+								end: {
+									line: endLine,
+									column: endColumn,
+								},
+							},
+							messageId: "multipleH1",
+						});
+					}
+				}
+			},
+
+			heading(node) {
+				if (node.depth === 1) {
+					h1Count++;
+					if (h1Count > 1) {
+						context.report({
+							loc: node.position,
+							messageId: "multipleH1",
+						});
+					}
+				}
+			},
+		};
+	},
+};