MD004 - Unordered list style should be consistent¶

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"
after-marker = 1      # Number of spaces after marker (default: 1)

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

Related rules¶

• MD005 - List indentation
• MD007 - Unordered list indentation
• MD030 - List marker spacing
• MD032 - Lists should be surrounded by blank lines