Skip to content

MD023 - Start headings at the beginning of lines

Aliases: heading-start-left

What this rule does

Checks that headings start at the beginning of the line without any indentation.

An indented level-1 ATX heading whose first word starts with a lowercase letter or a digit (# tag, # 123) is left alone: such a line is more often a hashtag or an issue reference than a heading.

Why this matters

  • Proper rendering: Indented headings may not be recognized by all Markdown processors
  • Clear structure: Headings at the line start make document hierarchy obvious
  • Consistency: Uniform alignment creates a professional appearance
  • Avoid confusion: Indented text with # symbols might be misinterpreted

Examples

✅ Correct

# Main Title
## Section Header
### Subsection
#### Detail Level

❌ Incorrect

   # Main Title
  ## Section Header
 ### Subsection
    #### Detail Level

🔧 Fixed

# Main Title
## Section Header
### Subsection
#### Detail Level

Automatic fixes

This rule automatically removes any leading spaces or tabs from heading lines, moving them to the beginning of the line.

Learn more

  • MD001: Use consistent heading levels
  • MD003: Use consistent heading style
  • MD022: Add blank lines around headings
  • MD026: Remove trailing punctuation in headings