@@ -2758,8 +2791,8 @@ an indented code block:
Fortunately, blank lines are usually not necessary and can be
deleted. The exception is inside `
` tags, but as described
-above, raw HTML blocks starting with `` *can* contain blank
-lines.
+[above][HTML blocks], raw HTML blocks starting with ``
+*can* contain blank lines.
## Link reference definitions
@@ -2811,7 +2844,7 @@ them.
```````````````````````````````` example
[Foo bar]:
-
+
'title'
[Foo bar]
@@ -2877,6 +2910,29 @@ The link destination may not be omitted:
[foo]
````````````````````````````````
+ However, an empty link destination may be specified using
+ angle brackets:
+
+```````````````````````````````` example
+[foo]: <>
+
+[foo]
+.
+foo
+````````````````````````````````
+
+The title must be separated from the link destination by
+whitespace:
+
+```````````````````````````````` example
+[foo]: (baz)
+
+[foo]
+.
+[foo]: (baz)
+[foo]
+````````````````````````````````
+
Both title and destination can contain backslash escapes
and literal backslashes:
@@ -3034,6 +3090,25 @@ and thematic breaks, and it need not be followed by a blank line.
````````````````````````````````
+```````````````````````````````` example
+[foo]: /url
+bar
+===
+[foo]
+.
+bar
+foo
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: /url
+===
+[foo]
+.
+===
+foo
+````````````````````````````````
+
Several [link reference definitions]
can occur one after another, without intervening blank lines.
@@ -3070,6 +3145,17 @@ are defined:
````````````````````````````````
+Whether something is a [link reference definition] is
+independent of whether the link reference it defines is
+used in the document. Thus, for example, the following
+document contains just a link reference definition, and
+no visible content:
+
+```````````````````````````````` example
+[foo]: /url
+.
+````````````````````````````````
+
## Paragraphs
@@ -3207,7 +3293,7 @@ aaa
# Container blocks
-A [container block] is a block that has other
+A [container block](#container-blocks) is a block that has other
blocks as its contents. There are two basic kinds of container blocks:
[block quotes] and [list items].
[Lists] are meta-containers for [list items].
@@ -3669,9 +3755,8 @@ in some browsers.)
The following rules define [list items]:
1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of
- blocks *Bs* starting with a [non-whitespace character] and not separated
- from each other by more than one blank line, and *M* is a list
- marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces, then the result
+ blocks *Bs* starting with a [non-whitespace character], and *M* is a
+ list marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces, then the result
of prepending *M* and the following spaces to the first line of
*Ls*, and indenting subsequent lines of *Ls* by *W + N* spaces, is a
list item with *Bs* as its contents. The type of the list item
@@ -3981,8 +4066,7 @@ A start number may not be negative:
2. **Item starting with indented code.** If a sequence of lines *Ls*
constitute a sequence of blocks *Bs* starting with an indented code
- block and not separated from each other by more than one blank line,
- and *M* is a list marker of width *W* followed by
+ block, and *M* is a list marker of width *W* followed by
one space, then the result of prepending *M* and the following
space to the first line of *Ls*, and indenting subsequent lines of
*Ls* by *W + 1* spaces, is a list item with *Bs* as its contents.
@@ -4458,9 +4542,10 @@ continued here.
6. **That's all.** Nothing that is not counted as a list item by rules
#1--5 counts as a [list item](#list-items).
-The rules for sublists follow from the general rules above. A sublist
-must be indented the same number of spaces a paragraph would need to be
-in order to be included in the list item.
+The rules for sublists follow from the general rules
+[above][List items]. A sublist must be indented the same number
+of spaces a paragraph would need to be in order to be included
+in the list item.
So, in this case we need two spaces indent:
@@ -5049,11 +5134,9 @@ item:
- b
- c
- d
- - e
- - f
- - g
- - h
-- i
+ - e
+ - f
+- g
.
- a
@@ -5063,8 +5146,6 @@ item:
- e
- f
- g
-- h
-- i
````````````````````````````````
@@ -5074,7 +5155,7 @@ item:
2. b
- 3. c
+ 3. c
.
-
@@ -5089,6 +5170,49 @@ item:
````````````````````````````````
+Note, however, that list items may not be indented more than
+three spaces. Here `- e` is treated as a paragraph continuation
+line, because it is indented more than three spaces:
+
+```````````````````````````````` example
+- a
+ - b
+ - c
+ - d
+ - e
+.
+
+````````````````````````````````
+
+And here, `3. c` is treated as in indented code block,
+because it is indented four spaces and preceded by a
+blank line.
+
+```````````````````````````````` example
+1. a
+
+ 2. b
+
+ 3. c
+.
+
+-
+
a
+
+-
+
b
+
+
+3. c
+
+````````````````````````````````
+
This is a loose list, because there is a blank line between
two of the list items:
@@ -5378,10 +5502,10 @@ Thus, for example, in
hilo`
````````````````````````````````
-
`hi` is parsed as code, leaving the backtick at the end as a literal
backtick.
+
## Backslash escapes
Any ASCII punctuation character may be backslash-escaped:
@@ -5415,6 +5539,7 @@ not have their usual Markdown meanings:
\* not a list
\# not a heading
\[foo]: /url "not a reference"
+\ö not a character entity
.
*not emphasized*
<br/> not a tag
@@ -5423,7 +5548,8 @@ not have their usual Markdown meanings:
1. not a list
* not a list
# not a heading
-[foo]: /url "not a reference"
+[foo]: /url "not a reference"
+ö not a character entity
````````````````````````````````
@@ -5521,13 +5647,23 @@ foo
## Entity and numeric character references
-All valid HTML entity references and numeric character
-references, except those occuring in code blocks and code spans,
-are recognized as such and treated as equivalent to the
-corresponding Unicode characters. Conforming CommonMark parsers
-need not store information about whether a particular character
-was represented in the source using a Unicode character or
-an entity reference.
+Valid HTML entity references and numeric character references
+can be used in place of the corresponding Unicode character,
+with the following exceptions:
+
+- Entity and character references are not recognized in code
+ blocks and code spans.
+
+- Entity and character references cannot stand in place of
+ special characters that define structural elements in
+ CommonMark. For example, although `*` can be used
+ in place of a literal `*` character, `*` cannot replace
+ `*` in emphasis delimiters, bullet list markers, or thematic
+ breaks.
+
+Conforming CommonMark parsers need not store information about
+whether a particular character was represented in the source
+using a Unicode character or an entity reference.
[Entity references](@) consist of `&` + any of the valid
HTML5 entity names + `;`. The
@@ -5548,22 +5684,22 @@ references and their corresponding code points.
[Decimal numeric character
references](@)
-consist of `&#` + a string of 1--8 arabic digits + `;`. A
+consist of `&#` + a string of 1--7 arabic digits + `;`. A
numeric character reference is parsed as the corresponding
Unicode character. Invalid Unicode code points will be replaced by
the REPLACEMENT CHARACTER (`U+FFFD`). For security reasons,
the code point `U+0000` will also be replaced by `U+FFFD`.
```````````````````````````````` example
-# Ӓ Ϡ � �
+# Ӓ Ϡ �
.
-# Ӓ Ϡ � �
+# Ӓ Ϡ �
````````````````````````````````
[Hexadecimal numeric character
references](@) consist of `&#` +
-either `X` or `x` + a string of 1-8 hexadecimal digits + `;`.
+either `X` or `x` + a string of 1-6 hexadecimal digits + `;`.
They too are parsed as the corresponding Unicode character (this
time specified with a hexadecimal numeral instead of decimal).
@@ -5578,9 +5714,13 @@ Here are some nonentities:
```````````````````````````````` example
&x; &#; &#x;
+�
+&#abcdef0;
&ThisIsNotDefined; &hi?;
.
  &x; &#; &#x;
+�
+&#abcdef0;
&ThisIsNotDefined; &hi?;
````````````````````````````````
@@ -5661,6 +5801,51 @@ text in code spans and code blocks:
````````````````````````````````
+Entity and numeric character references cannot be used
+in place of symbols indicating structure in CommonMark
+documents.
+
+```````````````````````````````` example
+*foo*
+*foo*
+.
+*foo*
+foo
+````````````````````````````````
+
+```````````````````````````````` example
+* foo
+
+* foo
+.
+* foo
+
+````````````````````````````````
+
+```````````````````````````````` example
+foo
bar
+.
+foo
+
+bar
+````````````````````````````````
+
+```````````````````````````````` example
+ foo
+.
+→foo
+````````````````````````````````
+
+
+```````````````````````````````` example
+[a](url "tit")
+.
+[a](url "tit")
+````````````````````````````````
+
+
## Code spans
A [backtick string](@)
@@ -5669,9 +5854,16 @@ preceded nor followed by a backtick.
A [code span](@) begins with a backtick string and ends with
a backtick string of equal length. The contents of the code span are
-the characters between the two backtick strings, with leading and
-trailing spaces and [line endings] removed, and
-[whitespace] collapsed to single spaces.
+the characters between the two backtick strings, normalized in the
+following ways:
+
+- First, [line endings] are converted to [spaces].
+- If the resulting string both begins *and* ends with a [space]
+ character, but does not consist entirely of [space]
+ characters, a single [space] character is removed from the
+ front and back. This allows you to include code that begins
+ or ends with backtick characters, which must be separated by
+ whitespace from the opening or closing backtick strings.
This is a simple code span:
@@ -5683,10 +5875,11 @@ This is a simple code span:
Here two backticks are used, because the code contains a backtick.
-This example also illustrates stripping of leading and trailing spaces:
+This example also illustrates stripping of a single leading and
+trailing space:
```````````````````````````````` example
-`` foo ` bar ``
+`` foo ` bar ``
.
foo ` bar
````````````````````````````````
@@ -5701,58 +5894,79 @@ spaces:
``
````````````````````````````````
+Note that only *one* space is stripped:
-[Line endings] are treated like spaces:
+```````````````````````````````` example
+` `` `
+.
+ ``
+````````````````````````````````
+
+The stripping only happens if the space is on both
+sides of the string:
```````````````````````````````` example
-``
-foo
-``
+` a`
.
-foo
+ a
````````````````````````````````
+Only [spaces], and not [unicode whitespace] in general, are
+stripped in this way:
+
+```````````````````````````````` example
+` b `
+.
+ b
+````````````````````````````````
-Interior spaces and [line endings] are collapsed into
-single spaces, just as they would be by a browser:
+No stripping occurs if the code span contains only spaces:
```````````````````````````````` example
-`foo bar
- baz`
+` `
+` `
.
-foo bar baz
+
+
````````````````````````````````
-Not all [Unicode whitespace] (for instance, non-breaking space) is
-collapsed, however:
+[Line endings] are treated like spaces:
```````````````````````````````` example
-`a b`
+``
+foo
+bar
+baz
+``
.
-a b
+foo bar baz
````````````````````````````````
+```````````````````````````````` example
+``
+foo
+``
+.
+foo
+````````````````````````````````
-Q: Why not just leave the spaces, since browsers will collapse them
-anyway? A: Because we might be targeting a non-HTML format, and we
-shouldn't rely on HTML-specific rendering assumptions.
-(Existing implementations differ in their treatment of internal
-spaces and [line endings]. Some, including `Markdown.pl` and
-`showdown`, convert an internal [line ending] into a
-`
` tag. But this makes things difficult for those who like to
-hard-wrap their paragraphs, since a line break in the midst of a code
-span will cause an unintended line break in the output. Others just
-leave internal spaces as they are, which is fine if only HTML is being
-targeted.)
+Interior spaces are not collapsed:
```````````````````````````````` example
-`foo `` bar`
+`foo bar
+baz`
.
-foo `` bar
+foo bar baz
````````````````````````````````
+Note that browsers will typically collapse consecutive spaces
+when rendering `` elements, so it is recommended that
+the following CSS be used:
+
+ code{white-space: pre-wrap;}
+
Note that backslash escapes do not work in code spans. All backslashes
are treated literally:
@@ -5768,6 +5982,19 @@ Backslash escapes are never needed, because one can always choose a
string of *n* backtick characters as delimiters, where the code does
not contain any strings of exactly *n* backtick characters.
+```````````````````````````````` example
+``foo`bar``
+.
+foo`bar
+````````````````````````````````
+
+```````````````````````````````` example
+` foo `` bar `
+.
+foo `` bar
+````````````````````````````````
+
+
Code span backticks have higher precedence than any other inline
constructs except HTML tags and autolinks. Thus, for example, this is
not parsed as emphasized text, since the second `*` is part of a code
@@ -5905,15 +6132,17 @@ of one or more `_` characters that is not preceded or followed by
a non-backslash-escaped `_` character.
A [left-flanking delimiter run](@) is
-a [delimiter run] that is (a) not followed by [Unicode whitespace],
-and (b) not followed by a [punctuation character], or
+a [delimiter run] that is (1) not followed by [Unicode whitespace],
+and either (2a) not followed by a [punctuation character], or
+(2b) followed by a [punctuation character] and
preceded by [Unicode whitespace] or a [punctuation character].
For purposes of this definition, the beginning and the end of
the line count as Unicode whitespace.
A [right-flanking delimiter run](@) is
-a [delimiter run] that is (a) not preceded by [Unicode whitespace],
-and (b) not preceded by a [punctuation character], or
+a [delimiter run] that is (1) not preceded by [Unicode whitespace],
+and either (2a) not preceded by a [punctuation character], or
+(2b) preceded by a [punctuation character] and
followed by [Unicode whitespace] or a [punctuation character].
For purposes of this definition, the beginning and the end of
the line count as Unicode whitespace.
@@ -6005,7 +6234,8 @@ The following rules define emphasis and strong emphasis:
[delimiter runs]. If one of the delimiters can both
open and close emphasis, then the sum of the lengths of the
delimiter runs containing the opening and closing delimiters
- must not be a multiple of 3.
+ must not be a multiple of 3 unless both lengths are
+ multiples of 3.
10. Strong emphasis begins with a delimiter that
[can open strong emphasis] and ends with a delimiter that
@@ -6015,7 +6245,8 @@ The following rules define emphasis and strong emphasis:
[delimiter runs]. If one of the delimiters can both open
and close strong emphasis, then the sum of the lengths of
the delimiter runs containing the opening and closing
- delimiters must not be a multiple of 3.
+ delimiters must not be a multiple of 3 unless both lengths
+ are multiples of 3.
11. A literal `*` character cannot occur at the beginning or end of
`*`-delimited emphasis or `**`-delimited strong emphasis, unless it
@@ -6634,7 +6865,19 @@ is precluded by the condition that a delimiter that
can both open and close (like the `*` after `foo`)
cannot form emphasis if the sum of the lengths of
the delimiter runs containing the opening and
-closing delimiters is a multiple of 3.
+closing delimiters is a multiple of 3 unless
+both lengths are multiples of 3.
+
+
+For the same reason, we don't get two consecutive
+emphasis sections in this example:
+
+```````````````````````````````` example
+*foo**bar*
+.
+foo**bar
+````````````````````````````````
+
The same condition ensures that the following
cases are all strong emphasis nested inside
@@ -6663,6 +6906,23 @@ omitted:
````````````````````````````````
+When the lengths of the interior closing and opening
+delimiter runs are *both* multiples of 3, though,
+they can match to create emphasis:
+
+```````````````````````````````` example
+foo***bar***baz
+.
+foobarbaz
+````````````````````````````````
+
+```````````````````````````````` example
+foo******bar*********baz
+.
+foobar***baz
+````````````````````````````````
+
+
Indefinite levels of nesting are possible:
```````````````````````````````` example
@@ -7198,15 +7458,16 @@ following rules apply:
A [link destination](@) consists of either
- a sequence of zero or more characters between an opening `<` and a
- closing `>` that contains no spaces, line breaks, or unescaped
+ closing `>` that contains no line breaks or unescaped
`<` or `>` characters, or
-- a nonempty sequence of characters that does not include
- ASCII space or control characters, and includes parentheses
- only if (a) they are backslash-escaped or (b) they are part of
- a balanced pair of unescaped parentheses. (Implementations
- may impose limits on parentheses nesting to avoid performance
- issues, but at least three levels of nesting should be supported.)
+- a nonempty sequence of characters that does not start with
+ `<`, does not include ASCII space or control characters, and
+ includes parentheses only if (a) they are backslash-escaped or
+ (b) they are part of a balanced pair of unescaped parentheses.
+ (Implementations may impose limits on parentheses nesting to
+ avoid performance issues, but at least three levels of nesting
+ should be supported.)
A [link title](@) consists of either
@@ -7219,7 +7480,8 @@ A [link title](@) consists of either
backslash-escaped, or
- a sequence of zero or more characters between matching parentheses
- (`(...)`), including a `)` character only if it is backslash-escaped.
+ (`(...)`), including a `(` or `)` character only if it is
+ backslash-escaped.
Although [link titles] may span multiple lines, they may not contain
a [blank line].
@@ -7269,9 +7531,8 @@ Both the title and the destination may be omitted:
link
````````````````````````````````
-
-The destination cannot contain spaces or line breaks,
-even if enclosed in pointy brackets:
+The destination can only contain spaces if it is
+enclosed in pointy brackets:
```````````````````````````````` example
[link](/my uri)
@@ -7279,13 +7540,14 @@ even if enclosed in pointy brackets:
[link](/my uri)
````````````````````````````````
-
```````````````````````````````` example
[link]()
.
-[link](</my uri>)
+link
````````````````````````````````
+The destination cannot contain line breaks,
+even if enclosed in pointy brackets:
```````````````````````````````` example
[link](foo
@@ -7295,7 +7557,6 @@ bar)
bar)
````````````````````````````````
-
```````````````````````````````` example
[link]()
@@ -7304,6 +7565,36 @@ bar>)
bar>)
````````````````````````````````
+The destination can contain `)` if it is enclosed
+in pointy brackets:
+
+```````````````````````````````` example
+[a]()
+.
+a
+````````````````````````````````
+
+Pointy brackets that enclose links must be unescaped:
+
+```````````````````````````````` example
+[link]()
+.
+[link](<foo>)
+````````````````````````````````
+
+These are not links, because the opening pointy bracket
+is not matched properly:
+
+```````````````````````````````` example
+[a](
+[a](c)
+.
+[a](<b)c
+[a](<b)c>
+[a](c)
+````````````````````````````````
+
Parentheses inside the link destination may be escaped:
```````````````````````````````` example
@@ -8411,7 +8702,7 @@ If you want a link after a literal `!`, backslash-escape the
as the link label.
A [URI autolink](@) consists of `<`, followed by an
-[absolute URI] not containing `<`, followed by `>`. It is parsed as
+[absolute URI] followed by `>`. It is parsed as
a link to the URI, with the URI as the link's label.
An [absolute URI](@),
@@ -8624,7 +8915,7 @@ a [single-quoted attribute value], or a [double-quoted attribute value].
An [unquoted attribute value](@)
is a nonempty string of characters not
-including spaces, `"`, `'`, `=`, `<`, `>`, or `` ` ``.
+including [whitespace], `"`, `'`, `=`, `<`, `>`, or `` ` ``.
A [single-quoted attribute value](@)
consists of `'`, zero or more
@@ -8745,9 +9036,13 @@ Illegal [whitespace]:
```````````````````````````````` example
< a><
foo>
+
.
< a><
-foo><bar/ >
+foo><bar/ >
+<foo bar=baz
+bim!bop />
````````````````````````````````
@@ -8944,10 +9239,10 @@ bar
Line breaks do not occur inside code spans
```````````````````````````````` example
-`code
+`code
span`
.
-code span
+code span
````````````````````````````````
@@ -9365,7 +9660,8 @@ just above `stack_bottom` (or the first element if `stack_bottom`
is NULL).
We keep track of the `openers_bottom` for each delimiter
-type (`*`, `_`). Initialize this to `stack_bottom`.
+type (`*`, `_`) and each length of the closing delimiter run
+(modulo 3). Initialize this to `stack_bottom`.
Then we repeat the following until we run out of potential
closers:
@@ -9397,7 +9693,7 @@ closers:
of the delimiter stack. If the closing node is removed, reset
`current_position` to the next element in the stack.
-- If none in found:
+- If none is found:
+ Set `openers_bottom` to the element before `current_position`.
(We know that there are no openers for this kind of closer up to and