Although most current markdown implementations allow arbitrary mixes of the supported list markers
+ to generate a single uniform list in the output, the Commonmark specification now requires that each change in marker starts a new list:
A list is a sequence of one or more list items of the same type. (…)
Two list items are of the same type if they begin with a list marker of the same type.
Two list markers are of the same type if
(a) they are bullet list markers using the same character (
(b) they are ordered list numbers with the same delimiter (either
(Please note that some implementations do weird things: Cebe treats a change in list item marker as a new nested list and Gambas uses plus
+ for ordered lists.)
I believe there are some valid, existing use cases of mixed-marker lists. Supporting these would require a slight change in philosophy: Lists that mix the bullet types are considered to associate special meaning with them.
If all three markers are being used, the list can be treated like a change log or diff.
Empty items are ignored except that they take part in determining the kind of list.
+ designates a new feature, minus
- a removed or deprecated one and asterisk
* is for general informational changes. It’s a matter of philosophy whether bug fixes belong into the
These conventions are followed more or less by many plain-text change logs already, even if they do not use markdown explicitly.
+ New feature, addition - Deprecated feature, removal, (bug fix) * Other change, informational, (bug fix)
If only plus
+ and hyphen-minus
- are mixed, the list is treated as a comparison of pros and cons.
As you can see below, the code highlighter used here recognizes that convention (because it auto-guesses the code to be a diff, not markdown):
+ Pro - Con
- is mixed with asterisk
*, this makes an agenda, i.e. a to-do, shopping or task list.
- introduces unfinished entries (“open”), the asterisk
* ones that already have been ticked off (“closed”).
Most existing flavors that support something like this use different syntax with square brackets
[+] or parentheses
( ) to mock checkboxes and radio buttons.
* breakfast - lunch - supper
If we anticipated an extension to support such advanced lists, would it be better to keep the current phrasing of the spec to make separate lists or would the universal existing practice of making it a single list be better suited?