MD004 - Unordered list style should be consistent
September 9, 2026 · View on GitHub
Aliases: ul-style
What this rule does
Ensures all unordered lists use the same marker (* or + or -) throughout your document.
Why this matters
- Visual consistency: Mixed list markers look unprofessional and disorganized
- Readability: Consistent markers make it easier to scan lists
- Maintenance: One style is easier to remember and apply
- Style guides: Most organizations standardize on one list marker
Examples
✅ Correct (using * throughout)
* Item 1
* Item 2
* Nested item 1
* Nested item 2
* Item 3
✅ Correct (using - throughout)
- Item 1
- Item 2
- Nested item 1
- Nested item 2
- Item 3
✅ Correct (using sublist style)
* Item 1
* Item 2
+ Nested item 1
+ Nested item 2
- Deep nested item 1
- Deep nested item 2
* Even deeper (cycles back to *)
* Item 3
❌ Incorrect
* Item 1
+ Item 2 (different marker)
- Nested item 1
* Nested item 2
- Item 3 (yet another marker)
🔧 Fixed
* Item 1
* Item 2
* Nested item 1
* Nested item 2
* Item 3
Configuration
[MD004]
style = "consistent" # Options: "consistent", "asterisk", "plus", "dash", "sublist"
Style options
"consistent"(default): Use the most prevalent marker in your document (in case of a tie, dash-is preferred as it's the GitHub default)"asterisk": Always use * markers"plus": Always use + markers"dash": Always use - markers"sublist": Each nesting level uses a different marker (cycles through *, +, -)
Automatic fixes
This rule automatically converts all list markers to match your configured style or the most prevalent marker in the document.
Learn more
- CommonMark lists - Technical specification
- Markdown Guide - Lists - List best practices