Struct MD001HeadingIncrement 

pub struct MD001HeadingIncrement {
    pub front_matter_title: bool,
    pub front_matter_title_pattern: Option<Regex>,
}

Rule MD001: Heading levels should only increment by one level at a time

See docs/md001.md for full documentation, configuration, and examples.

This rule enforces a fundamental principle of document structure: heading levels should increase by exactly one level at a time to maintain a proper document hierarchy.

Purpose

Proper heading structure creates a logical document outline and improves:

• Readability for humans
• Accessibility for screen readers
• Navigation in rendered documents
• Automatic generation of tables of contents

Examples

Correct Heading Structure

# Heading 1
## Heading 2
### Heading 3
## Another Heading 2

Incorrect Heading Structure

# Heading 1
### Heading 3 (skips level 2)
#### Heading 4

Behavior

This rule:

• Tracks the heading level throughout the document
• Validates that each new heading is at most one level deeper than the previous heading
• Allows heading levels to decrease by any amount (e.g., going from ### to #)
• Works with both ATX (#) and Setext (underlined) heading styles

Fix Behavior

When applying automatic fixes, this rule:

• Changes the level of non-compliant headings to be one level deeper than the previous heading
• Preserves the original heading style (ATX or Setext)
• Maintains indentation and other formatting

Rationale

Skipping heading levels (e.g., from h1 to h3) can confuse readers and screen readers by creating gaps in the document structure. Consistent heading increments create a proper hierarchical outline essential for well-structured documents.

Front Matter Title Support

When front_matter_title is enabled (default: true), this rule recognizes a title: field in YAML/TOML frontmatter as an implicit level-1 heading. This allows documents like:

---
title: My Document
---

## First Section

Without triggering a warning about skipping from H1 to H2, since the frontmatter title counts as the H1.

Fields

front_matter_title: bool

Whether to treat frontmatter title field as an implicit H1

front_matter_title_pattern: Option<Regex>

Optional regex pattern to match custom title fields in frontmatter

Implementations

impl MD001HeadingIncrement

pub fn new(front_matter_title: bool) -> Self

Create a new instance with specified settings

pub fn with_pattern(front_matter_title: bool, pattern: Option<String>) -> Self

Create a new instance with a custom pattern for matching title fields

Trait Implementations

impl Clone for MD001HeadingIncrement

fn clone(&self) -> MD001HeadingIncrement

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MD001HeadingIncrement

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MD001HeadingIncrement

fn default() -> Self

Returns the “default value” for a type.

impl Rule for MD001HeadingIncrement

fn name(&self) -> &'static str

fn description(&self) -> &'static str

fn check(&self, ctx: &LintContext<'_>) -> LintResult

fn fix(&self, ctx: &LintContext<'_>) -> Result<String, LintError>

fn category(&self) -> RuleCategory

Get the category of this rule for selective processing

fn should_skip(&self, ctx: &LintContext<'_>) -> bool

Check if this rule should quickly skip processing based on content

fn as_any(&self) -> &dyn Any

fn from_config(config: &Config) -> Box<dyn Rule>

where Self: Sized,

Factory: create a rule from config (if present), or use defaults.

fn default_config_section(&self) -> Option<(String, Value)>

Returns the rule name and default config table if the rule has config. If a rule implements this, it MUST be defined on the impl Rule for ... block, not just the inherent impl.

fn config_schema(&self) -> Option<(String, Value)>

Returns the rule name and every config key the rule accepts, for validation.

fn skippable_by_category(&self) -> bool

Whether the content-category prefilter may skip this rule.

fn config_aliases(&self) -> Option<HashMap<String, String>>

Returns config key aliases for this rule This allows rules to accept alternative config key names for backwards compatibility

fn polymorphic_config_keys(&self) -> &'static [&'static str]

Returns the list of config keys whose deserializer accepts more than one TOML type (e.g. either a scalar or a list). The schema is built from a serialized default that can only encode one variant, so the validator would reject the alternative form. The registry replaces the schema entry for each listed key with a polymorphic sentinel so type checking is skipped while the key name is still validated. The registry rewrites Rule::config_schema, so default_config_section() keeps returning the clean user-facing default.

fn fix_capability(&self) -> FixCapability

Declares the fix capability of this rule

fn cross_file_scope(&self) -> CrossFileScope

Declares cross-file analysis requirements for this rule

fn contribute_to_index( &self, _ctx: &LintContext<'_>, _file_index: &mut FileIndex, )

Contribute data to the workspace index during linting

fn cross_file_check( &self, _file_path: &Path, _file_index: &FileIndex, _workspace_index: &WorkspaceIndex, ) -> LintResult

Perform cross-file validation after all files have been linted

fn observes_suppressions(&self) -> bool

Whether this rule reports on the inline comments that suppressed warnings

fn check_suppressions( &self, _ctx: &LintContext<'_>, _report: &SuppressionReport, ) -> LintResult

Report on a document’s inline disable comments