feat: add frontmatterTitle option to heading-increment

[xbinaryx]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request?

This pull request adds a new frontmatterTitle option to the heading-increment rule. The rule will treat a frontmatter title as a level 1 heading for the purpose of heading increment checks, ensuring that heading levels are not skipped after a frontmatter title.

What changes did you make? (Give an overview)

• Added a frontmatterTitle option to the heading-increment rule, allowing users to specify a regex pattern to detect a title in frontmatter blocks.
• Added tests to verify the new behavior.
• Updated documentation to describe the new option and its usage.

Related Issues

Fixes #443

Is there anything you'd like reviewers to focus on?

[Copilot]

Pull Request Overview

This PR introduces a frontmatterTitle option to the heading-increment rule so that a matching title in frontmatter counts as an H1, preventing skipped-heading errors. It adds a helper, integrates frontmatter handlers, expands tests, and updates documentation.

• Introduce frontmatterHasTitle in util.js and use it in heading-increment
• Expand heading-increment rule with schema, default options, and frontmatter listeners
• Add tests covering YAML/TOML/JSON frontmatter variations and update docs

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/rules/heading-increment.test.js	Added valid/invalid cases for frontmatter title handling
src/util.js	Added frontmatterHasTitle helper
src/rules/no-multiple-h1.js	Imported helper and updated JSDoc typedefs (unused import)
src/rules/heading-increment.js	Added schema, defaultOptions, and YAML/TOML/JSON handlers
docs/rules/heading-increment.md	Documented new frontmatterTitle option

[Copilot]

The imported frontmatterHasTitle is never used in this rule. Either integrate it to support a frontmatterTitle option or remove the unused import.

[Copilot]

JSDoc does not recognize @import as a type declaration. Replace this with a valid import-based typedef, e.g., @typedef {import("../types.js").MarkdownRuleDefinition<...>} NoMultipleH1RuleDefinition.

Suggested change

	* @import { MarkdownRuleDefinition } from "../types.js";
	* @typedef {import("../types.js").MarkdownRuleDefinition} MarkdownRuleDefinition

[Copilot]

JSDoc does not support an @import tag for types. Use @typedef {import("../types.js").MarkdownRuleDefinition<...>} HeadingIncrementRuleDefinition to ensure the type is correctly recognized.

Suggested change

	* @import { MarkdownRuleDefinition } from "../types.js";
	* @typedef {"skippedHeading"} HeadingIncrementMessageIds
	* @typedef {[{ frontmatterTitle?: string }]} HeadingIncrementOptions
	* @typedef {MarkdownRuleDefinition<{ RuleOptions: HeadingIncrementOptions, MessageIds: HeadingIncrementMessageIds }>}
	* @typedef {"skippedHeading"} HeadingIncrementMessageIds
	* @typedef {[{ frontmatterTitle?: string }]} HeadingIncrementOptions
	* @typedef {import("../types.js").MarkdownRuleDefinition<{ RuleOptions: HeadingIncrementOptions, MessageIds: HeadingIncrementMessageIds }>}