A list item may not contain blocks that are separated by more than one blank line. Thus, two blank lines will end a list, unless the two blanks are contained in a fenced code block.
Indented code blocks can contain multiple subsequent blank lines as well (as example 56 shows); I don’t understand why the two would be handled differently here.
If there’s a compelling reason for this, then it should be at least rephrased, because as it stands, the second sentence does not follow from the first.
My reasoning was as follows: One of the main motivations for
introducing the two-blanks-break-out rule in the first place was to deal
with complications raised by indented code blocks. (For example, how do
you have an indented code block immediately following a list?)
So, imagine we want the following:
1. list item
indented code inside item 1
indented code block which is not part of
the list item but whose content is indented
four spaces (so that the whole block is indented
eight spaces)
The two-blanks-rule allows this, but if the two blanks were
allowed to be part of the indented code block, we’d just get a
single indented code block inside the list item.
This is a rather contrived example, and perhaps this isn’t likely
to come up much. So I’d be open to allowing two blank lines inside
an indented code block in a list item. Indeed, I think this would
make the spec more coherent, since the distinction between fenced
and indented code blocks is unexpected here, and the current wording:
A list item may not contain blocks that are separated by more than
one blank line.
doesn’t actually tell you that two blank lines inside an indented
code block (which is after all a single block, not two blocks
separated by two blank lines) is treated differently.
I like the double-blank rule very much, precisely because it fixes the “code after list” problem (here’s my Meta Stack Exchange post on that issue), even though I still maintain that it’s a very rare issue (in 99% of the cases, you’d want the code block as part of the list item; it’s rare that you start something new with code as opposed to text).
And yes, I think the 8-space indent problem is even less likely to come up (and with fenced code blocks, there’s even a reasonable workaround for this rare case), so I’d vote for consistency.
I would prefer if indented code blocks behaved the same regardless of where they are placed. So in that example, it should stay as one code block.
In general, instead of inventing weird rules that break the otherwise consistent behavior, I’d prefer to just have some kind of “block breaker” that breaks whatever block there was previously and resets the parsing process.
For example <!-- --> works well for that. I do it all the time on SO, when I want to post multiple but separated code blocks.
I would prefer if indented code blocks behaved the same regardless of
where they are placed. So in that example, it should stay as one code
block.
In general, instead of inventing weird rules that break the otherwise
consistent behavior, I’d prefer to just have some kind of “block
breaker” that breaks whatever block there was previously and resets the
parsing process.
The only other container block, besides lists and list items, are
block quotes. According to this spec, they already break on a single
blank line. So there’s no particular need for a general block breaker.
However, it is true that the two-blanks rule is a bit weird and adds
quite a bit of complexity to the spec and parsers. And, with fenced
code blocks, there’s less of a need for it than there used to be.
In addition to allowing adjacent-but-separate code blocks, the “block breaker” can be used to explicitly move a code block outside a list, which might otherwise be part of the last list item.
Of course, it is also important for >blockquotes and indented code blocks to have similar coalescing/separation behavior, to avoid confusion.
The “code block after list” problem does have a solution in SMD, and I like it much better than the <!-- --> thing, which I’ve always considered a hack. To be precise it has two solutions; fenced code blocks and the double-newline rule.
To be honest though, I’ve never seen the problem of putting a code block directly after a list as a major problem in the first place, because I can’t think of a real-life text where you’d want to do that. If you have a list and then code, it’s one of two situations:
The code block adds/belongs to the thought in the text immediately before it. And that text is the last list item. And if that’s the case, then the code block should be part of the list item, which original Markdown already allows unambiguously.
The code block is separate from the previous thought, it starts something new. In that case, it should be preceded by an explanatory section of text (which would also be outside of the list) that puts this code block into context and perspective. This section of text would already act as a block breaker between the list and the code block.
But for anyone who disagrees with my opinion on this, SMD solves this problem, and it does this better than with the HTML comment workaround.
Almost the same thing applies to directly subsequent code blocks. If the second code block is necessarily separate from the first one, then it should have some sort of textual content before it that makes it clear to the reader what this separation is about. This may be as little as “Here’s the HTML: [code block 1] And here’s the corresponding CSS: [code block 2]”, but there should be something.
Of course with fenced code blocks you can still achieve this in a non-hacky way, should you still want it.
In any case, the point of this thread is the inconsistency that currently inside list items, fenced code blocks may contain double newlines, but indented codeblocks cannot. The problem this solves is that you can have an indented code block at the end of a list item, immediately follow by an indented codeblock outside the list that also starts with an internally indented line of code. Such a code block seems like an extremely rare case on its own, in addition to the fact that this situation is really a combination of my two points about code directly after a list and about two subsequent code blocks.
So the issue this solves is almost non-existent, but the solution comes at the cost that moving an indented code block from top level into a list items by just moving its left margin may cause the code block to suddenly break.
Just because you can’t that doesn’t mean there isn’t one. One simple example would be something like this: “In the following code excerpt, there were 5 things changed: […]”, followed by a list and then the code.
Your argumentation builds upon your personal standard on how you think text should be written. But Markdown is a language meant for authors, and we usually would want to give authors the freedom to write their texts in whatever way they want. If they don’t want to put things like “This is the HTML:”, “This is the CSS:” in front of their code blocks, they are absolutely fine to do so.
And saying that fenced code blocks can solve this is true but not really relevant. I personally don’t like fenced code blocks; indented code is more readable to me (when looking at the source), so I’d always prefer putting in some “block breaker” (even if it’s a hack) to separate it (especially since it’s also a good visual separator).
I do consider it a hack too, yes. But it’s working fine. My idea was to introduce a proper code blocker to Markdown that can be used to break either block, being it code, list or a quote. For example a \\ on a separate line could do that or something similar.
So the issue this solves is almost non-existent, but the solution comes at the cost that moving an indented code block from top level into a list items by just moving its left margin may cause the code block to suddenly break.
This does strike me as a serious strike against the two-blank-line rule.
It’s bad in general if the meaning of a document-part changes when we
put it into a list item.
[Sorry for the late reply - I missed a great deal of substantive
discussion right after the launch, when I was getting too much email to
deal with. Starting to look back over the earlier comments on this
forum.]