doesn't that make you wonder?

John MacFarlane jgm at
Tue Oct 18 20:27:07 EDT 2011

+++ Allan Odgaard [Oct 18 11 10:10 ]:

> On 18 Oct 2011, at 01:47, John MacFarlane wrote:


> > […] I have argued before on this list that the "four space rule" is implicit in the markdown syntax specification. But it's not quite explicit, hence the trouble.


> Maybe I am misunderstanding your reference but the specification¹ seems fairly explicit:


> | List items may consist of multiple paragraphs.

> | Each subsequent paragraph in a list item must

> | be indented by either 4 spaces or one tab

This concerns multi-paragraph list items:

- first paragraph of list item

second paragraph of same list item

I was talking about nested lists:

- item

- subitem

Some implementations require "- subitem" to be indented four
spaces, while others allow three space indentation. (Incidentally,
I first noticed this when I saw nested lists indented three spaces in an early
version of the TextMate manual; I then confirmed that treated
these as nested lists, contrary to the impression I'd formed from the
syntax specification.)

One could argue that the nested list counts as a "subsequent paragraph," in
which case the passage you quoted from the spec settles the issue. I
wouldn't say that's obvious, though. Interestingly, the syntax description for
lists doesn't say anything about nested lists. It does say explicitly how to
include a code block and a block quotation under list items, but it says
nothing about how you include another list under a list item. Since
other block elements need to be indented four spaces to be included
under a list item, it seems reasonable that lists do too, but that isn't
said explicitly.

> > So you may find that what is a nested list on one markdown

> > implementation is a single-level list on another.


> Adding to that, whether or not the list items are wrapped with <p>.


> > I made the case long ago that there should be a formal grammar for markdown, but the idea was never popular on this list.


> I think there are many who would like to see a formal/exhaustive specification, and no-one can be happy about say, text editor syntax highlight doing it one way, the local preview showing it another, and when posting the document online, yet another interpretation is applied.


> The problem is partly that several want it to be about the user, so it doesn’t matter there are 30 lines of code to try and guess what the user meant, rather than have the user be more explicit (it is after all meant as sort of an anti-markup language).

This is an interesting difference between markdown and reStructuredText,
by the way. On the reStructuredText mailing list, one often finds
proposals rejected with the words "Too implicit."

But there isn't really an incompatibility between formal specification and
"trying to guess what the user meant" -- it just means that the formal
specification is going to be more complicated.

That said, if I were designing a "non-markup" language from scratch, there are
many things I'd do differently. I think there's an unoccupied sweet
spot somewhere between markdown and reStructuredText.


More information about the Markdown-Discuss mailing list