list corner case

John MacFarlane jgm at
Tue Sep 9 21:26:28 EDT 2008

It has been interesting to hear people's thoughts on this. Let me
summarize the considerations I've been weighing.

Against (b): it's just too unexpected. Nothing in the markdown
syntax description would lead one to expect that changing the list
marker would start a sublist. I'm curious, though, to hear whether
Michel Fortin has a rationale for doing it this way in PHP Markdown;
I think he's the only (b)-category implementer who hasn't weighed
in on this discussion.

One argument for (c) that initially appealed to me is that it allows
the writer to have two consecutive lists without any intervening
block element--something that is otherwise impossible in markdown.
So it adds expressive power, whereas (a) just gives you another
(more obscure) way to express something you can already express.

The more I thought about it, though, the less impressive I found
this consideration. For (c) only gives you a way to have consecutive
lists if one is ordered and one unordered. It doesn't help if you
want to have two consecutive ordered lists, e.g.:

1. foo
2. bar

1. baz
2. quux

This gets parsed as one big ordered list by all implementations.
It seems to me that if markdown needs a way to express consecutive
lists, it needs a *general* way to do so, one that will work even
if the lists are of the same type.

Another argument for (c) is that John Gruber's markdown syntax
description gives the definite impression that ALL the markers
in an ordered list are numbers, and that ALL the markers in an
unordered list are *, +, or -. "Unordered lists use asterisks, pluses,
and hyphens — interchangably — as list markers..." "Ordered lists
use numbers followed by periods..." Gruber does say that "the actual
numbers you use to mark the list have no effect on the HTML output
Markdown produces," but note that he says "numbers" here; there is no
suggestion that you can use bullet markers in an ordered list.
On this ground it might be argued that (a) would not be the expected

On the other hand, (a) is the most well-established interpretation,
since it's the interpretation of and all the implementations
that have essentially copied its regular expression transformations.
I know there's markdown out there that continues ordered lists with
unordered list markers (I found one instance of this when I replaced
BlueCloth with rpeg-markdown and someone complained that his lists
had changed). I've also seen at least one markdown cheat-sheet that
advertises this behavior <>.

So even though I think (c) is a slightly better interpretation of the
markdown syntax document, I'm inclined to defer to the canonical
implementation here, in the interest of not breaking existing documents.
That means that, even though my two implementations fall into groups
(b) and (c), I'm starting to favor (a).


+++ John MacFarlane [Sep 07 08 18:24 ]:

> I'm curious how people think the following *should* be interpreted:


> - one

> 2. two




> As you can see, implementations split into three groups here:


> (a) treat as an unordered list

>, Python markdown, MultiMarkdown, BlueCloth, MarkdownJ,

> Showdown


> (b) treat as an unordered list with an ordered sublist

> PHP Markdown, Text::Markdown, Pandoc


> (c) treat as an unordered list followed by an ordered list

> Maruku, Discount, PEG Markdown


> John


> _______________________________________________

> Markdown-Discuss mailing list

> Markdown-Discuss at



More information about the Markdown-Discuss mailing list