@@ -1447,11 +1558,11 @@ A processing instruction:
.
';
?>
.
';
?>
.
@@ -1946,8 +2057,8 @@ bbb
.
Final spaces are stripped before inline parsing, so a paragraph
-that ends with two or more spaces will not end with a hard line
-break:
+that ends with two or more spaces will not end with a [hard line
+break](#hard-line-break):
.
aaa
@@ -2375,7 +2486,8 @@ An [ordered list marker](#ordered-list-marker)
is a sequence of one of more digits (`0-9`), followed by either a
`.` character or a `)` character.
-The following rules define [list items](#list-item):
+The following rules define [list items](#list-item):
1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of
blocks *Bs* starting with a non-space character and not separated
@@ -2826,9 +2938,11 @@ Four spaces indent gives a code block:
some or all of the indentation from one or more lines in which the
next non-space character after the indentation is
[paragraph continuation text](#paragraph-continuation-text) is a
- list item with the same contents and attributes.
+ list item with the same contents and attributes.
-Here is an example with lazy continuation lines:
+Here is an example with [lazy continuation
+lines](#lazy-continuation-line):
.
1. A paragraph
@@ -3005,6 +3119,21 @@ A list item may be empty:
.
+A list item can contain a header:
+
+.
+- # Foo
+- Bar
+ ---
+ baz
+.
+
+.
+
### Motivation
John Gruber's Markdown spec says the following about list items:
@@ -3210,12 +3339,12 @@ of an [ordered list](#ordered-list) is determined by the list number of
its initial list item. The numbers of subsequent list items are
disregarded.
-A list is [loose](#loose) if it any of its constituent list items are
-separated by blank lines, or if any of its constituent list items
-directly contain two block-level elements with a blank line between
-them. Otherwise a list is [tight](#tight). (The difference in HTML output
-is that paragraphs in a loose with are wrapped in `
` tags, while
-paragraphs in a tight list are not.)
+A list is [loose](#loose) if it any of its constituent
+list items are separated by blank lines, or if any of its constituent
+list items directly contain two block-level elements with a blank line
+between them. Otherwise a list is [tight](#tight).
+(The difference in HTML output is that paragraphs in a loose list are
+wrapped in `
` tags, while paragraphs in a tight list are not.)
Changing the bullet or ordered list delimiter starts a new list:
@@ -3247,6 +3376,87 @@ Changing the bullet or ordered list delimiter starts a new list:
.
+In CommonMark, a list can interrupt a paragraph. That is,
+no blank line is needed to separate a paragraph from a following
+list:
+
+.
+Foo
+- bar
+- baz
+.
+
Foo
+
+.
+
+`Markdown.pl` does not allow this, through fear of triggering a list
+via a numeral in a hard-wrapped line:
+
+.
+The number of windows in my house is
+14. The number of doors is 6.
+.
+
The number of windows in my house is
+
+- The number of doors is 6.
+
+.
+
+Oddly, `Markdown.pl` *does* allow a blockquote to interrupt a paragraph,
+even though the same considerations might apply. We think that the two
+cases should be treated the same. Here are two reasons for allowing
+lists to interrupt paragraphs:
+
+First, it is natural and not uncommon for people to start lists without
+blank lines:
+
+ I need to buy
+ - new shoes
+ - a coat
+ - a plane ticket
+
+Second, we are attracted to a
+
+> [principle of uniformity](#principle-of-uniformity):
id="principle-of-uniformity"> if a span of text has a certain
+> meaning, it will continue to have the same meaning when put into a list
+> item.
+
+(Indeed, the spec for [list items](#list-item) presupposes this.)
+This principle implies that if
+
+ * I need to buy
+ - new shoes
+ - a coat
+ - a plane ticket
+
+is a list item containing a paragraph followed by a nested sublist,
+as all Markdown implementations agree it is (though the paragraph
+may be rendered without `
` tags, since the list is "tight"),
+then
+
+ I need to buy
+ - new shoes
+ - a coat
+ - a plane ticket
+
+by itself should be a paragraph followed by a nested sublist.
+
+Our adherence to the [principle of uniformity](#principle-of-uniformity)
+thus inclines us to think that there are two coherent packages:
+
+1. Require blank lines before *all* lists and blockquotes,
+ including lists that occur as sublists inside other list items.
+
+2. Require blank lines in none of these places.
+
+[reStructuredText](http://docutils.sourceforge.net/rst.html) takes
+the first approach, for which there is much to be said. But the second
+seems more consistent with established practice with Markdown.
+
There can be blank lines between items, but two blank lines end
a list:
@@ -3463,8 +3673,8 @@ This is a tight list, because the blank lines are in a code block:
.
This is a tight list, because the blank line is between two
-paragraphs of a sublist. So the inner list is loose while
-the other list is tight:
+paragraphs of a sublist. So the sublist is loose while
+the outer list is tight:
.
- a
@@ -3650,7 +3860,8 @@ If a backslash is itself escaped, the following character is not:
\emphasis
.
-A backslash at the end of the line is a hard line break:
+A backslash at the end of the line is a [hard line
+break](#hard-line-break):
.
foo\
@@ -4095,21 +4306,42 @@ for efficient parsing strategies that do not backtrack:
(c) it is not followed by an ASCII alphanumeric character.
9. Emphasis begins with a delimiter that [can open
- emphasis](#can-open-emphasis) and includes inlines parsed
- sequentially until a delimiter that [can close
+ emphasis](#can-open-emphasis) and ends with a delimiter that [can close
emphasis](#can-close-emphasis), and that uses the same
- character (`_` or `*`) as the opening delimiter, is reached.
+ character (`_` or `*`) as the opening delimiter. The inlines
+ between the open delimiter and the closing delimiter are the
+ contents of the emphasis inline.
10. Strong emphasis begins with a delimiter that [can open strong
- emphasis](#can-open-strong-emphasis) and includes inlines parsed
- sequentially until a delimiter that [can close strong
- emphasis](#can-close-strong-emphasis), and that uses the
- same character (`_` or `*`) as the opening delimiter, is reached.
-
-11. In case of ambiguity, strong emphasis takes precedence. Thus,
- `**foo**` is `
foo`, not `
foo`,
- and `***foo***` is `
foo`, not
- `
foo` or `
foo`.
+ emphasis](#can-open-strong-emphasis) and ends with a delimiter that
+ [can close strong emphasis](#can-close-strong-emphasis), and that uses the
+ same character (`_` or `*`) as the opening delimiter. The inlines
+ between the open delimiter and the closing delimiter are the
+ contents of the strong emphasis inline.
+
+Where rules 1--10 above are compatible with multiple parsings,
+the following principles resolve ambiguity:
+
+11. An interpretation `
...` is always preferred to
+ `
...`.
+
+12. An interpretation `
...` is always
+ preferred to `
..`.
+
+13. Earlier closings are preferred to later closings. Thus,
+ when two potential emphasis or strong emphasis spans overlap,
+ the first takes precedence: for example, `*foo _bar* baz_`
+ is parsed as `
foo _bar baz_` rather than
+ `*foo
bar* baz`. For the same reason,
+ `**foo*bar**` is parsed as `
foobar*`
+ rather than `
foo*bar`.
+
+14. Inline code spans, links, images, and HTML tags group more tightly
+ than emphasis. So, when there is a choice between an interpretation
+ that contains one of these elements and one that does not, the
+ former always wins. Thus, for example, `*[foo*](bar)` is
+ parsed as `*
foo*` rather than as
+ `
[foo](bar)`.
These rules can be illustrated through a series of examples.
@@ -4721,6 +4953,46 @@ More cases with mismatched delimiters:
***foo bar
.
+The following cases illustrate rule 13:
+
+.
+*foo _bar* baz_
+.
+
foo _bar baz_
+.
+
+.
+**foo bar* baz**
+.
+
foo bar baz*
+.
+
+The following cases illustrate rule 14:
+
+.
+*[foo*](bar)
+.
+
*foo*
+.
+
+.
+*
+.
+
*
+.
+
+.
+*
+.
+
*
+.
+
+.
+*a`a*`
+.
+
*aa*
+.
+
## Links
A link contains a [link label](#link-label) (the visible text),
@@ -5859,7 +6131,8 @@ Backslash escapes do not work in HTML attributes:
## Hard line breaks
A line break (not in a code span or HTML tag) that is preceded
-by two or more spaces is parsed as a linebreak (rendered
+by two or more spaces is parsed as a [hard line
+break](#hard-line-break)
(rendered
in HTML as a `
` tag):
.
@@ -6209,5 +6482,3 @@ an `emph`.
The document can be rendered as HTML, or in any other format, given
an appropriate renderer.
-
-