Markdownlint Rules Reference

Complete reference of markdownlint rules enforced in our configuration.

Rules Enforced

Rule	Description	Fix
MD001	Heading levels increment by one	Don't skip from H1 to H3
MD003	Heading style (ATX vs setext)	Use `#` syntax consistently
MD004	List marker style	Use consistent markers (all `-` or all `*`)
MD007	List indentation	Use 2 or 4 spaces consistently
MD009	No trailing spaces	Remove spaces at line ends
MD012	No multiple blank lines	Use single blank lines
MD018	Space after hash in heading	`# Heading` not `#Heading`
MD019	Multiple spaces after hash	Use single space after `#`
MD022	Headings surrounded by blank lines	Add blank lines before/after
MD024	Duplicate headings (siblings only)	OK if not siblings
MD025	Single H1 per document	Only one top-level heading
MD026	No trailing punctuation in headings	Remove `!?.` from headings
MD030	Space after list marker	`- Item` not `-Item`
MD031	Code blocks surrounded by blank lines	Add spacing around code
MD032	Lists surrounded by blank lines	Add spacing around lists
MD033	Inline HTML (specific elements allowed)	Use allowed elements only
MD037	No spaces inside emphasis	`text` not ` text `
MD040	Code blocks should specify language	Add language to ``` blocks
MD046	Code block style (fenced only)	Use ``` not indentation
MD047	Single trailing newline	Files must end with newline
MD049	Emphasis style consistency	Use consistent `*` or `_` style
MD050	Strong emphasis style consistency	Use consistent `**` or `__` style

Rule	Description	Why Disabled
MD013	Line length	Write naturally, no arbitrary limits
MD041	First line heading	Badges, images, etc. are fine at top

Heading rules: MD001, MD003, MD018, MD019, MD022, MD024, MD025, MD026

List rules: MD004, MD007, MD030, MD032

Code block rules: MD031, MD040, MD046

Whitespace rules: MD009, MD012, MD047

Inline rules: MD033, MD034, MD037, MD049, MD050

For detailed explanations of each rule: