Struct MD002FirstHeadingH1

pub struct MD002FirstHeadingH1 { /* private fields */ }

Rule MD002: First heading should be a top-level heading

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

This rule enforces that the first heading in a document is a top-level heading (typically h1), which establishes the main topic or title of the document.

Purpose

• Document Structure: Ensures proper document hierarchy with a single top-level heading
• Accessibility: Improves screen reader navigation by providing a clear document title
• SEO: Helps search engines identify the primary topic of the document
• Readability: Provides users with a clear understanding of the document’s main subject

Configuration Options

The rule supports customizing the required level for the first heading:

MD002:
  level: 1  # The heading level required for the first heading (default: 1)

Setting level: 2 would require the first heading to be an h2 instead of h1.

Examples

Correct (with default configuration)

# Document Title

## Section 1

Content here...

## Section 2

More content...

Incorrect (with default configuration)

## Introduction

Content here...

# Main Title

More content...

Behavior

This rule:

• Ignores front matter (YAML metadata at the beginning of the document)
• Works with both ATX (#) and Setext (underlined) heading styles
• Only examines the first heading it encounters
• Does not apply to documents with no headings

Fix Behavior

When applying automatic fixes, this rule:

• Changes the level of the first heading to match the configured level
• Preserves the original heading style (ATX, closed ATX, or Setext)
• Maintains indentation and other formatting

Rationale

Having a single top-level heading establishes the document’s primary topic and creates a logical structure. This follows semantic HTML principles where each page should have a single <h1> element that defines its main subject.

Implementations

impl MD002FirstHeadingH1

pub fn new(level: u32) -> Self

pub fn from_config_struct(config: MD002Config) -> Self

Trait Implementations

impl Clone for MD002FirstHeadingH1

fn clone(&self) -> MD002FirstHeadingH1

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MD002FirstHeadingH1

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

Formats the value using the given formatter.

impl Default for MD002FirstHeadingH1

fn default() -> MD002FirstHeadingH1

Returns the “default value” for a type.

impl Rule for MD002FirstHeadingH1

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 be skipped

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 as_any(&self) -> &dyn Any

fn as_maybe_document_structure(&self) -> Option<&dyn MaybeDocumentStructure>

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 from_config(config: &Config) -> Box<dyn Rule>

where Self: Sized,

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

fn check_with_structure( &self, ctx: &LintContext<'_>, _structure: &DocumentStructure, ) -> LintResult

Enhanced check method using document structure By default, calls the regular check method if not overridden

fn check_with_ast( &self, ctx: &LintContext<'_>, _ast: &MarkdownAst, ) -> LintResult

AST-based check method for rules that can benefit from shared AST parsing By default, calls the regular check method if not overridden

fn check_with_structure_and_ast( &self, ctx: &LintContext<'_>, _structure: &DocumentStructure, _ast: &MarkdownAst, ) -> LintResult

Combined check method using both document structure and AST By default, calls the regular check method if not overridden

fn uses_ast(&self) -> bool

Check if this rule can benefit from AST parsing

fn uses_document_structure(&self) -> bool

Check if this rule can benefit from document structure

fn as_maybe_ast(&self) -> Option<&dyn MaybeAst>