Unordered list markers#
In Markdown, to create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list:
- Item A
- Item B
- Nested item B.1* Item A
* Item B
* Nested item B.1All three render identically. Which one you type is a matter of style — and that is exactly what linters check.
MD004 (ul-style)#
The Markdown linter rule MD004 (ul-style) configures and enforces the type of marker used for unordered lists across your documents.
- Tags:
bullet,ul - Aliases:
ul-style - Fixable: Some violations can be fixed by tooling
- Parameters (
style):consistent(default): Allows any symbol (*,-,+), as long as all lists throughout the document match the style of the first list.asterisk: Requires asterisks (*).dash: Requires dashes (-).plus: Requires plus signs (+).sublist: Allows each nested list level (sublist) to use a distinct symbol that differs from its parent level.
The default configuration is usually “consistent”:
{
"ul-style": {
"style": "consistent"
}
}For example, when sublist style is configured, the following document is valid because the outer-most indent uses asterisks, the middle indent uses plus signs, and the inner-most indent uses dashes:
* Item 1
+ Item 2
- Item 3
+ Item 4
* Item 5
+ Item 6Why I prefer dashes#
The default may be asterisks, but I find dashes (-) the common style and the easiest to read. There is a practical reason too: AI agents write dashes almost everywhere, and they use asterisks (**) heavily for bold text. Enforcing asterisks for lists therefore creates noise — a * at the start of a line is ambiguous between a list marker and bold formatting at a glance.
Do not force existing documents#
Sometimes a document already uses asterisks (*) throughout, and it is perfectly consistent. I do not want to churn that document just to satisfy a rule. A linter should not be the reason to rewrite clean, consistent content.
Option 1: configure the dash style#
You can update your JSON configuration (.markdownlint.json) so the rule accepts dashes instead:
{
"ul-style": {
"style": "dash"
}
}Now dashes pass. But asterisk-only documents still fail, so the churn problem remains.
Option 2: disable the rule#
The rule adds little value — the marker choice is cosmetic. I prefer to simply disable it:
{
"ul-style": false
}Now both styles coexist freely. Each document keeps its own convention, no forced rewrites, and the linter stays quiet.
Conclusion#
Style rules are opinions, not bugs. MD004 only cares about which marker you pick, and every document picks one consistently anyway. Configuring "dash" still punishes existing asterisk documents, so I choose "ul-style": false and let each file keep its own style.