Reconsidering "two blank lines breaks out of lists"

Spec
1

The current spec says that two blank lines (except in a fenced code block) terminates all containing lists. I’d like to reconsider this rule. It is inconsistent with the principle of uniformity that guides some of the spec’s other decisions, and with the “basic case” (rule 1) in the spec for list items. For the following text is two paragraphs:

aaa


bbb

so, by the principle of uniformity (and rule 1 for list items), we’d expect the following to be a list item containing the same two paragraphs:

- aaa


  bbb

but because of the tacked-on “two blank lines breaks out of lists” rule, it is instead interpreted as a list item with one paragraph, followed by a separate paragraph not in the list item.

I’ve come to think that the “two blank lines breaks out of lists” rule is more trouble than it’s worth. It creates surprise by breaking uniform patterns. Why did we think we needed it? The idea was first suggested long ago on the markdown-discuss list, in response to the question “how can I have a code block after a list item?” The problem was that if you wanted the sequence (LIST) (CODE BLOCK), you couldn’t write

1.  list item

    code block

because the text code block would be interpreted as part of the list item, not a separate block after the list. The recommended solution was to insert an HTML comment:

1.  list item

<!-- -->

    code block

which works just fine, though it’s a bit ugly. But now we have an even better solution: just use a fenced code block:

1.  list item

```
code block
````

So, the addition of fenced code blocks seems to have solved the problem that first motivated the two-blanks break out of lists idea.

There is one other kind of case that might be thought to motivate the two-blanks rule: a case where you want to have two separate lists of the same type, instead of a single list with two items:

- one
- two


- one
- two

This is not so common. But here, again, some CommonMark enhancements can give us what we want without the two-blanks rule:

- one
- two

+ one
+ two

Any thoughts on this? The proposal is to remove the two-blanks-break-out-of-lists rule.

2 Likes
2

Replying to my own post, I think the current spec could be clarified if rule 1 for list items explicitly said “a sequence of lines not containing two consecutive blank lines that are not in a fenced code block.” And, I’m not sure there’s really a conflict with the principle of uniformity, which only applies when you have lines in a list item, as long as we’re explicit that a list item can’t be formed containing two blank lines (not in fenced code). Still, I’d be interested in any thoughts about whether the two-blanks rule should or should not be kept.

3

I have no real use examples for this cases (don’t know where list + list or list + code needed). Will be ok with any choice.

4

I agree that making the experience of marking up documents less surprising is a positive thing. My only concern is how this might effect existing Markdown documents that contain two lists in a row separated by a double break.

5

I consider the change useful. Now I know that also VLC wants to migrate to a flavour of markdown for their documentation (btw somebody tried to contact Hugo developers?)

6

+++ Chris Alley [Dec 01 14 07:31 ]:

I agree that making the experience of marking up the document less surprising is a positive thing. My only concern is how this might effect existing Markdown documents that contain two lists in a row separated by a double break.

I’m guessing there should be very few of these, since CommonMark is the
only variant I’m aware of that implements the “two-blanks breaks out of
lists” rule, and it hasn’t been around very long.

7

+++ Luca Barbato [Dec 01 14 12:16 ]:

I consider the change useful.

Do you mean that you favor keeping the “two blank linse break out of lists” rule, or removing it?

8

I’m fine with removing it.

9

For me the two blank lines seem rather natural way of finishing the list - at least that is what I would try as a novice when I notice in the preview that some other block element (paragraph, code etc.) is for some reason nested in the list item - I would first try hitting Enter a few times in between.

Visually the two blank lines are a large enough divider so that the content after them do not seem related to the list.

1 Like
10

It occurs to me that, since we already have the \ for line break, why not use it for “block break” as well?:

    code block 1
\
    code block 2

Two lists:
1. item
2. item
\
1. item
2. item

A line with just a \ would be a (non-fenced) block terminator.

Of course this doesn’t solve ambiguities in old documents (which still need to be standardized), but it would make authoring new documents simpler.

2 Likes
11

Interesting suggestion.

+++ Andrés M [Jan 07 15 01:36 ]: