Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MD023 - Headings Must Start at the Beginning of the Line

Severity: Warning
Category: Headings
Auto-fix: ✓ Available

Rule Description

This rule ensures headings start at the beginning of the line without any leading spaces or tabs. Indented headings are not valid in standard markdown.

Why This Rule Exists

Headings at line start are important because:

  • Indented text with hashes may be interpreted as code or regular text
  • Ensures headings are properly recognized by all parsers
  • Maintains consistent document structure
  • Follows CommonMark specification

Examples

❌ Incorrect (violates rule)

  # Indented heading
    ## Another indented heading
	### Tab-indented heading

✅ Correct

# Heading at line start
## Another proper heading
### Correctly positioned heading

Configuration

This rule has no configuration options.

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

  • Remove all leading whitespace (spaces and tabs) before headings
  • Preserve the heading level and content
  • Maintain proper heading structure

Apply Fix

# Fix indented headings
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

  • You're documenting markdown syntax and showing indented hash examples
  • Your content includes code blocks with hash-prefixed comments

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD023"]

Disable Inline

<!-- mdbook-lint-disable MD023 -->
    # This indented text is intentional
<!-- mdbook-lint-enable MD023 -->
  • MD018 - No space after hash on ATX heading
  • MD019 - Multiple spaces after hash on ATX heading
  • MD022 - Headings should be surrounded by blank lines
  • MD025 - Multiple top-level headings in the same document
  • MD026 - Trailing punctuation in heading

References