Requiring a blank line between a paragraph and list

Spec
21

As I said in the posts I linked to on your issue, the principle of uniformity is the main thing that sways me towards allowing lists to interrupt paragraphs. The meaning of a text should not change when you put it in a list item.

So, if this is not a list:

Words:
+ bar
+ baz

then it should not be a list when you put it in a list item:

1.  Words:
    + bar
    + baz

Many implementations break this principle of uniformity.
But it’s important to keep it. Indeed, it’s required by the way the spec for list items is written.

I’d be even more happy to require the blank line in both contexts – a top-level paragraph and a paragraph in a list – so that you needed to write, in the second example:

1.  Words:

    + bar
    + baz

reStructuredText imposes a requirement like this. But it would be a pretty major backwards-compatibility breakage, so I don’t think anyone considered it seriously.

2 Likes
22

There’s no question that lists should interrupt paragraphs, so the final resolution of this topic is IMHO correct.

This pattern is one I see users typing, almost literally every single day in Discourse:

Stuff
- item
- item

And they absolutely (and reasonably) expect that to be a paragraph followed by a list. Now with CommonMark it will be!

23

I see your reasoning, and don’t doubt that this pattern is indeed “common practice”—even thought I wouldn’t use or recommend it, if only for the simple reason that it is highly “non-portable”.

However, allowing any line that “looks like” a list item to interrupt any old paragraph in the CommonMark syntax, for the sole purpose that:

Now with CommonMark it will be!

seems a bit far-reaching in my point of view: in particular it introduces a whole range of possibilities to “inadvertently” have list items recognized inside a paragraph where none are intended—I think this is a well-known problem in cases like:

Stuff that I
- nor anyone else -
would never write in the
1. place.

Situations like this (admittedly contrived) example do occur in practice when paragraph text gets re-formatted. I for one have turned to using NBSP to make it clear (for the formatter, and for CommonMark) that “-~” and “1.~” are “just text” and in no way list item markers [the tilde “~” here stands for my use of NBSP]. But I don’t think this is a common way of writing CommonMark, nor that it should be.

Is there any chance to “tighten” the syntax rules in a way that

  1. your example is still recognized as a list, but
  2. my example is not?

Maybe by recognizing that your example matches the pattern

  • the first line in the block is a “vanilla line”,
  • each subsequent line is a “list item” line,

while mine does not?

Or would it be too “extreme” to require additional markup for your example to work, like (off he top of my head and for illustration only):

:Stuff
- item
- item

or, as had been mentioned elsewhere, maybe detect a COLON at the end of the first line in a block, and use this to “enable” list items in your example:

Stuff:
- item
- item

This would obviously much simpler to implement (and to explain, IMO!) that the “pattern-matching” convention above.

And a “COLON at the end of the first line in a block” is, I think, unlikely to be left there inadvertently as a result of re-flowing a paragraph (though not impossible, but in any case easier to see and to fix than having to eyeball every line start in the re-flowed paragraph …).

Any thoughts on this (old topic!)—or is it simply “just too late”?

24

Sorry, you are arriving extremely late to this party. Perhaps you can focus these walls of text on the things that have not been definitively decided? :wink:

25

Sorry. I thought, based on the wild variation that Babelmark shows in this case, that this matter was not definitively decided—at least not in the wider Markdown realm (the “compatibility argument”).