# Requiring a blank line between a paragraph and list **URL:** \ **Category:** Spec\ **Created:** [September 20, 2014, 6:06pm UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657 "2014-09-20T18:06:59Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![Burt\_Harris](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/burt_harris/32/368_2.png) [@Burt\_Harris](https://talk.commonmark.org/u/Burt_Harris)\ **Post date:** [September 20, 2014, 6:06pm UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/1 "2014-09-20T18:06:59Z")
Continuing the discussion from [CommonMark Danger: Markdown Extensions w/o Flavors](http://talk.commonmark.org/t/commonmark-danger-markdown-extensions-w-o-flavors/648/5): > [@jgm](#): > > In initial discussions leading up to the spec, the issue of whether to require a blank line between a paragraph and a following list did come up. I favored requiring it, both to increase backwards compatibility and because of a symmetry argument. (Because of “laziness”, you need a blank line between a list and a following paragraph, so by symmetry it makes sense to require a blank line between a paragraph and a following list.) Others argued that users are likely to create lists without the intervening blank line; this is intuitive and would strike any reader as obviously a paragraph followed by a list: > > ```auto > My shopping list: > - eggs > - butter > - bread > > ``` > > There are arguments on both sides, and it’s definitely an issue that could be reconsidered. ---
**Author:** ![Burt\_Harris](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/burt_harris/32/368_2.png) [@Burt\_Harris](https://talk.commonmark.org/u/Burt_Harris)\ **Post date:** [September 20, 2014, 6:17pm UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/2 "2014-09-20T18:17:11Z")
I think you were right to favor requiring it. While I agree with the intuitiveness of that notation, and agree that _other_ lightweight languages (like YAML) see it that way, [Babelmark 2](http://johnmacfarlane.net/babelmark2/?text=%23%23+The+Quadratic+Equation+%23%23%0AA+ __quadratic+equation__ +is+any+equation+having+the+form%3A%0A%0A%3E++*ax*%3Csup%3E2%3C%2Fsup%3E%0A%3E++%2B+*bx*%0A%3E++%2B+*c*%0A%3E++%3D+0%0A%0Awhere+*a%2C+b%2C*+and+*c*+represent+numbers%2C+%0Asuch+that+*a*+is+not+equal+to+0.) clearly doesn’t show that interpretation has any degree of commonality between markdown flavors. It strikes me that punctuation used in combination is a more clear indication of intent than whitespace. So I note the colon you used in that example, and suggest that lines ending in a colon _might_ be considered a special contextual maker, that could alter the interpretation of subsequent lines. Of course a blank line should work too. Let’s explore that in the context of my earlier example: ```auto ## The Quadratic Equation ## A __quadratic equation__ is any equation having the form: > *ax*2 > + *bx* > + *c* > = 0 where *a, b,* and *c* represent numbers, such that *a* is not equal to 0. ``` What happens if I [remove the first blank line](http://johnmacfarlane.net/babelmark2/?text=%23%23+The+Quadratic+Equation+%23%23%0AA+ __quadratic+equation__ +is+any+equation+having+the+form%3A%0A%3E++*ax*%3Csup%3E2%3C%2Fsup%3E%0A%3E++%2B+*bx*%0A%3E++%2B+*c*%0A%3E++%3D+0%0A%0Awhere+*a%2C+b%2C*+and+*c*+represent+numbers%2C+%0Asuch+that+*a*+is+not+equal+to+0.%60)? IMHO pandoc 1.13.1 and RedCarpet 2.1.1 misread my intent. The colon on line two might give a processor a hint that the blockquote following should be respected without a blank line. P.S. this also seems to reveal a possible bug in Babelmark2, as the preview view seems broken. ---
**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\ **Post date:** [September 22, 2014, 10:03am UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/3 "2014-09-22T10:03:14Z")
It is “babel” as in > **[Tower of Babel](https://en.wikipedia.org/wiki/Tower_of_Babel)** > > The Tower of Babel (Hebrew: .mw-parser-output .script-hebrew,.mw-parser-output .script-Hebr{font-size:1.15em;font-family:"SBL Hebrew","SBL BibLit","Frank Ruehl CLM","Taamey Frank CLM","Ezra SIL","Ezra SIL SR","Keter Aram Tsova","Taamey Ashkenaz","Taamey David CLM","Keter YG","Shofar","David CLM","Hadasim CLM","Simple CLM","Nachlieli",Cardo,Alef,"Noto Serif Hebrew","Noto Sans Hebrew","David Libre",David,"Times New Roman",Gisha,Arial,FreeSerif,FreeSans}מִגְדַּל בָּבֶל‎, Migdal Bavel) narrative i... ---
**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\ **Post date:** [September 22, 2014, 10:08am UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/4 "2014-09-22T10:08:11Z")
> [@Burt\_Harris](#): > > While I agree with the intuitiveness of that notation, and agree that other lightweight languages (like YAML) see it that way, Babelmark 2 clearly doesn’t show that interpretation has any degree of commonality between markdown flavors. Considering [the cited example](http://johnmacfarlane.net/babelmark2/?text=My+shopping+list%3A%0A-+eggs%0A-+butter%0A-+bread), Babelmark says: - 4 implementations interpret as para + list - 19 implementations interpret as para only I think the data says _most_ Markdown implementations do in fact require the line between. ---
**Author:** ![Burt\_Harris](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/burt_harris/32/368_2.png) [@Burt\_Harris](https://talk.commonmark.org/u/Burt_Harris)\ **Post date:** [September 23, 2014, 3:37am UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/5 "2014-09-23T03:37:26Z")
> [@codinghorror](#): > > Can you please edit your posts to spell “Babel” correctly? There’s a reason I posted the wikipedia article above I’d be happy to but frankly I wasn’t sure how/where I misspelled it. I was looking, but didn’t see it, but now I gather you mean `s/Babble/Babbel/g` 🙂 I think I’ve fixed it now, everwhere but your in quote of my statement. ---
**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\ **Post date:** [September 23, 2014, 7:56am UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/6 "2014-09-23T07:56:31Z")
Can you please edit your posts to spell “Babel” correctly? There’s a reason I posted the wikipedia article above. ---
**Author:** ![ComplexPoint](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/c/5f9b8f/32.png) [@ComplexPoint](https://talk.commonmark.org/u/ComplexPoint)\ **Post date:** [September 23, 2014, 9:19am UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/7 "2014-09-23T09:19:45Z")
Supply-side stats like those in the Babelmark table are, of course, easier to obtain, but the demand-side figures would be more useful in the design of high quality tools for users. It would be interesting to know: - What proportion of edit events involve insertion of a line first time ? - and what proportion involve subsequent editing to add a further line ? A graphical model weighted with that kind of data would allow more intelligent behaviour than a crude normative rule-base. ---
**Author:** ![PeterNLewis](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/peternlewis/32/431_2.png) [@PeterNLewis](https://talk.commonmark.org/u/PeterNLewis)\ **Post date:** [September 23, 2014, 9:41am UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/8 "2014-09-23T09:41:34Z")
Speaking just as a user, and having posted this as a bug in Discourse, I can say it is really annoying to require a blank line in this context. Its very clear what the user intention is if they write: ``` These three things: * one * two * three ``` Having that produce anything other than a list is a bug IMNVHO. It also is substantially ugly in the text to add a blank line there, and since the text may be being displayed as plain text in other formats (eg plain text email), this is definitely a problem. The fact that nineteen implementations require it most likely says more about the testing of those implementations than any real intent. ---
**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\ **Post date:** [September 23, 2014, 11:36am UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/9 "2014-09-23T11:36:32Z")
Hmmmmmm… wonder if `:` at the end of a line always signify ‘next paragraph’ or list. And if so, can there ever be a situation where it is still a new paragraph/list/etc… without `:` at end of line. ---
**Author:** ![mcwumbly](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mcwumbly/32/100_2.png) [@mcwumbly](https://talk.commonmark.org/u/mcwumbly)\ **Post date:** [September 23, 2014, 1:25pm UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/10 "2014-09-23T13:25:52Z")
Yep, [this is the most common mistake](http://talk.commonmark.org/t/default-line-break-handling-is-inconvenient/280/4?u=mcwumbly) I see people making who are new to markdown as well. I have never noticed it implemented any other way in practice, so I’ve gotten used to it. The topic linked above has a number of legitimate reasons not to consider line breaks as new paragraphs by default in general, so its worth a read. If lists could be special without any major pitfalls I think it would better meet user expectations. _especially_ when the "treat line breaks as paragraphs option is used" like this. ---
**Author:** ![Burt\_Harris](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/burt_harris/32/368_2.png) [@Burt\_Harris](https://talk.commonmark.org/u/Burt_Harris)\ **Post date:** [September 23, 2014, 4:48pm UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/11 "2014-09-23T16:48:52Z")
> [@PeterNLewis](#): > > Speaking just as a user, and having posted this as a bug in Discourse, I can say it is really annoying to require a blank line in this context. Its very clear what the user intention is if they write: Thanks Peter, I absolutely understand this, and value a user point of view. But in doing language design, I think it’s important we establish a clear priority between two potential goals for CommonMark, that may frequently be in conflict moving forward if we do not address them now: - The goal to be “as compatible as possible” - The goal to resolve minor annoyances and/or frequent mistakes. I believe that both these goals can be accommodated, but only thorough formalization of the concept of flavors and versions. These concepts may be a little fuzzy because they are not yet well defined in the CommonMark context, but I don’t think they will be onerous to implement or use. But right now, without flavors and versions I believe we should put design-for-compatibility above design-by-annoyance, or risk CommonMark becoming just another YAMF and making the real problem that lead to CommonMark’s creation (the lack of user and document portability between platforms) worse. Today, CommonMark is not final, and getting from here to there may look bit like making sausage. To people who fall closer to the user role than the implementer role, some of this process needed to refine the specification may seem unnecessarily ugly, but I hope you’ll trust me when I say that “clear intent” becomes anything but clear when attempting to parse natural languages in production quality code. ---
**Author:** ![ComplexPoint](https://cdn.commonmark.org/letter_avatar_proxy/v2/letter/c/5f9b8f/32.png) [@ComplexPoint](https://talk.commonmark.org/u/ComplexPoint)\ **Post date:** [September 23, 2014, 6:57pm UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/12 "2014-09-23T18:57:16Z")
> [@Burt\_Harris](#): > > but I hope you’ll trust me when I say that “clear intent” becomes anything but clear when attempting to parse natural languages in production quality code. When the domain of discourse is this constrained (a few elements of document structure), and the set of tokens this small (newlines, prefixes, inline emphases etc), the challenge is really not great, especially if some data on user habits has been collected. ---
**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\ **Post date:** [September 24, 2014, 4:25pm UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/13 "2014-09-24T16:25:51Z")
It is true that most implementations require the blank line. (And, although the requirement is not in John Gruber’s syntax description, this issue was explicitly discussed; see the links [here](https://pairlist6.pair.net/pipermail/markdown-discuss/2014-September/003156.html) for the relevant history.) There is a serious issue here about how heavily backwards compatibility should weigh. I must say, it would weigh much more heavily for me if there were a chance of avoiding fragmentation. But John Gruber has made it pretty clear that there is not. (I did ask him whether he could get behind this effort if we removed divergences like this, but there was no uptake.) If we are to be working on CommonMark instead of Markdown, then perhaps it is a good opportunity to rethink some things that may have been ill advised in the original. The first observation to make is that, no matter which way we go on this, there will be inputs that will not behave as their writers intended. However, I think these will be much more common if we do require the blank line than if we do not. Burt\_Harris’s original example is not as ordinary a piece of text as, for example: ```auto TODO: - fix bugs - write documentation ``` Either way we go, there will be some inputs where manual escaping is necessary to get the intended interpretation. Now, it seems to me that there is a strong reason for NOT requiring the blank lines. Even in Gruber’s Markdown, blank lines are not required inside a list item. So, this gives you a list item containing a paragraph followed by a bullet list: ```auto 1. Foo - Bar - Baz ``` CommonMark uses the principle that the meaning of a block of text should not change when it is put into a list item. It follows, then, that this should be a paragraph followed by a bullet list: ```auto Foo - Bar - Baz ``` (Indeed, the way the spec for list items is written _requires_ that this property hold.) I think this is the least surprising behavior for users. Hence, I conclude, either we should require the blank line between a paragraph and a list everywhere – even in sublist contexts (which is what reStructuredText does) – or we should require it nowhere. ---
**Author:** ![codinghorror](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/codinghorror/32/2_2.png) [@codinghorror](https://talk.commonmark.org/u/codinghorror)\ **Post date:** [September 24, 2014, 5:55pm UTC](https://talk.commonmark.org/t/requiring-a-blank-line-between-a-paragraph-and-list/657/14 "2014-09-24T17:55:00Z")
Based on this discussion, and the cited examples/data, I am persuaded that we should support **requiring a blank line nowhere**. That is, I think para - foo - bar should work as is (e.g. that should be a `