Couldn't find wdiff. Falling back to builtin diff colouring... Diff: spec.txt - spec.txt
 spec.txt   spec.txt 
--- ---
title: CommonMark Spec title: CommonMark Spec
author: John MacFarlane author: John MacFarlane
version: 0.26 version: 0.27
date: '2016-07-15' date: '2016-11-18'
license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)' license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)'
... ...
# Introduction # Introduction
## What is Markdown? ## What is Markdown?
Markdown is a plain text format for writing structured documents, Markdown is a plain text format for writing structured documents,
based on conventions used for indicating formatting in email and based on conventions used for indicating formatting in email and
usenet posts. It was developed in 2004 by John Gruber, who wrote usenet posts. It was developed in 2004 by John Gruber, who wrote
skipping to change at line 1872 skipping to change at line 1872
## HTML blocks ## HTML blocks
An [HTML block](@) is a group of lines that is treated An [HTML block](@) is a group of lines that is treated
as raw HTML (and will not be escaped in HTML output). as raw HTML (and will not be escaped in HTML output).
There are seven kinds of [HTML block], which can be defined There are seven kinds of [HTML block], which can be defined
by their start and end conditions. The block begins with a line that by their start and end conditions. The block begins with a line that
meets a [start condition](@) (after up to three spaces meets a [start condition](@) (after up to three spaces
optional indentation). It ends with the first subsequent line that optional indentation). It ends with the first subsequent line that
meets a matching [end condition](@), or the last line of meets a matching [end condition](@), or the last line of
the document or other [container block](@), if no line is encountered that meets the the document or other [container block]), if no line is encountered that meets t he
[end condition]. If the first line meets both the [start condition] [end condition]. If the first line meets both the [start condition]
and the [end condition], the block will contain just that line. and the [end condition], the block will contain just that line.
1. **Start condition:** line begins with the string `<script`, 1. **Start condition:** line begins with the string `<script`,
`<pre`, or `<style` (case-insensitive), followed by whitespace, `<pre`, or `<style` (case-insensitive), followed by whitespace,
the string `>`, or the end of the line.\ the string `>`, or the end of the line.\
**End condition:** line contains an end tag **End condition:** line contains an end tag
`</script>`, `</pre>`, or `</style>` (case-insensitive; it `</script>`, `</pre>`, or `</style>` (case-insensitive; it
need not match the start tag). need not match the start tag).
skipping to change at line 1902 skipping to change at line 1902
5. **Start condition:** line begins with the string 5. **Start condition:** line begins with the string
`<![CDATA[`.\ `<![CDATA[`.\
**End condition:** line contains the string `]]>`. **End condition:** line contains the string `]]>`.
6. **Start condition:** line begins the string `<` or `</` 6. **Start condition:** line begins the string `<` or `</`
followed by one of the strings (case-insensitive) `address`, followed by one of the strings (case-insensitive) `address`,
`article`, `aside`, `base`, `basefont`, `blockquote`, `body`, `article`, `aside`, `base`, `basefont`, `blockquote`, `body`,
`caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`, `caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,
`dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`, `dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`,
`footer`, `form`, `frame`, `frameset`, `h1`, `head`, `header`, `hr`, `footer`, `form`, `frame`, `frameset`,
`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`,
`html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`, `html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`,
`meta`, `nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`, `meta`, `nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,
`section`, `source`, `summary`, `table`, `tbody`, `td`, `section`, `source`, `summary`, `table`, `tbody`, `td`,
`tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed `tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed
by [whitespace], the end of the line, the string `>`, or by [whitespace], the end of the line, the string `>`, or
the string `/>`.\ the string `/>`.\
**End condition:** line is followed by a [blank line]. **End condition:** line is followed by a [blank line].
7. **Start condition:** line begins with a complete [open tag] 7. **Start condition:** line begins with a complete [open tag]
or [closing tag] (with any [tag name] other than `script`, or [closing tag] (with any [tag name] other than `script`,
skipping to change at line 3415 skipping to change at line 3416
blocks *Bs* starting with a [non-whitespace character] and not separated 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 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 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 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 *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 list item with *Bs* as its contents. The type of the list item
(bullet or ordered) is determined by the type of its list marker. (bullet or ordered) is determined by the type of its list marker.
If the list item is ordered, then it is also assigned a start If the list item is ordered, then it is also assigned a start
number, based on the ordered list marker. number, based on the ordered list marker.
Exceptions: When the list item interrupts a paragraph---that Exceptions: When the first list item in a [list] interrupts
is, when it starts on a line that would otherwise count as a paragraph---that is, when it starts on a line that would
[paragraph continuation text]---then (a) the lines *Ls* must otherwise count as [paragraph continuation text]---then (a)
not begin with a blank line, and (b) if the list item is the lines *Ls* must not begin with a blank line, and (b) if
ordered, the start number must be 1. the list item is ordered, the start number must be 1.
For example, let *Ls* be the lines For example, let *Ls* be the lines
```````````````````````````````` example ```````````````````````````````` example
A paragraph A paragraph
with two lines. with two lines.
indented code indented code
> A block quote. > A block quote.
skipping to change at line 4458 skipping to change at line 4459
we don't have a "first paragraph" to measure from? Rule #2 simply stipulates we don't have a "first paragraph" to measure from? Rule #2 simply stipulates
that in such cases, we require one space indentation from the list marker that in such cases, we require one space indentation from the list marker
(and then the normal four spaces for the indented code). This will match the (and then the normal four spaces for the indented code). This will match the
four-space rule in cases where the list marker plus its initial indentation four-space rule in cases where the list marker plus its initial indentation
takes four spaces (a common case), but diverge in other cases. takes four spaces (a common case), but diverge in other cases.
## Lists ## Lists
A [list](@) is a sequence of one or more A [list](@) is a sequence of one or more
list items [of the same type]. The list items list items [of the same type]. The list items
may be separated by single [blank lines], but two may be separated by any number of blank lines.
blank lines end all containing lists.
Two list items are [of the same type](@) Two list items are [of the same type](@)
if they begin with a [list marker] of the same type. if they begin with a [list marker] of the same type.
Two list markers are of the Two list markers are of the
same type if (a) they are bullet list markers using the same character same type if (a) they are bullet list markers using the same character
(`-`, `+`, or `*`) or (b) they are ordered list numbers with the same (`-`, `+`, or `*`) or (b) they are ordered list numbers with the same
delimiter (either `.` or `)`). delimiter (either `.` or `)`).
A list is an [ordered list](@) A list is an [ordered list](@)
if its constituent list items begin with if its constituent list items begin with
skipping to change at line 4535 skipping to change at line 4535
<p>Foo</p> <p>Foo</p>
<ul> <ul>
<li>bar</li> <li>bar</li>
<li>baz</li> <li>baz</li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
`Markdown.pl` does not allow this, through fear of triggering a list `Markdown.pl` does not allow this, through fear of triggering a list
via a numeral in a hard-wrapped line: via a numeral in a hard-wrapped line:
```````````````````````````````` markdown ``` markdown
The number of windows in my house is The number of windows in my house is
14. The number of doors is 6. 14. The number of doors is 6.
```````````````````````````````` ```
Oddly, though, `Markdown.pl` *does* allow a blockquote to Oddly, though, `Markdown.pl` *does* allow a blockquote to
interrupt a paragraph, even though the same considerations might interrupt a paragraph, even though the same considerations might
apply. apply.
In CommonMark, we do allow lists to interrupt paragraphs, for In CommonMark, we do allow lists to interrupt paragraphs, for
two reasons. First, it is natural and not uncommon for people two reasons. First, it is natural and not uncommon for people
to start lists without blank lines: to start lists without blank lines:
I need to buy ``` markdown
- new shoes I need to buy
- a coat - new shoes
- a plane ticket - a coat
- a plane ticket
```
Second, we are attracted to a Second, we are attracted to a
> [principle of uniformity](@): > [principle of uniformity](@):
> if a chunk of text has a certain > if a chunk of text has a certain
> meaning, it will continue to have the same meaning when put into a > meaning, it will continue to have the same meaning when put into a
> container block (such as a list item or blockquote). > container block (such as a list item or blockquote).
(Indeed, the spec for [list items] and [block quotes] presupposes (Indeed, the spec for [list items] and [block quotes] presupposes
this principle.) This principle implies that if this principle.) This principle implies that if
* I need to buy ``` markdown
- new shoes * I need to buy
- a coat - new shoes
- a plane ticket - a coat
- a plane ticket
```
is a list item containing a paragraph followed by a nested sublist, is a list item containing a paragraph followed by a nested sublist,
as all Markdown implementations agree it is (though the paragraph as all Markdown implementations agree it is (though the paragraph
may be rendered without `<p>` tags, since the list is "tight"), may be rendered without `<p>` tags, since the list is "tight"),
then then
I need to buy ``` markdown
- new shoes I need to buy
- a coat - new shoes
- a plane ticket - a coat
- a plane ticket
```
by itself should be a paragraph followed by a nested sublist. by itself should be a paragraph followed by a nested sublist.
Since it is well established Markdown practice to allow lists to Since it is well established Markdown practice to allow lists to
interrupt paragraphs inside list items, the [principle of interrupt paragraphs inside list items, the [principle of
uniformity] requires us to allow this outside list items as uniformity] requires us to allow this outside list items as
well. ([reStructuredText](http://docutils.sourceforge.net/rst.html) well. ([reStructuredText](http://docutils.sourceforge.net/rst.html)
takes a different approach, requiring blank lines before lists takes a different approach, requiring blank lines before lists
even inside other list items.) even inside other list items.)
skipping to change at line 5343 skipping to change at line 5350
Interior spaces and [line endings] are collapsed into Interior spaces and [line endings] are collapsed into
single spaces, just as they would be by a browser: single spaces, just as they would be by a browser:
```````````````````````````````` example ```````````````````````````````` example
`foo bar `foo bar
baz` baz`
. .
<p><code>foo bar baz</code></p> <p><code>foo bar baz</code></p>
```````````````````````````````` ````````````````````````````````
Not all [Unicode whitespace] (for instance, non-breaking space) is
collapsed, however:
```````````````````````````````` example
`a  b`
.
<p><code>a  b</code></p>
````````````````````````````````
Q: Why not just leave the spaces, since browsers will collapse them 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 anyway? A: Because we might be targeting a non-HTML format, and we
shouldn't rely on HTML-specific rendering assumptions. shouldn't rely on HTML-specific rendering assumptions.
(Existing implementations differ in their treatment of internal (Existing implementations differ in their treatment of internal
spaces and [line endings]. Some, including `Markdown.pl` and spaces and [line endings]. Some, including `Markdown.pl` and
`showdown`, convert an internal [line ending] into a `showdown`, convert an internal [line ending] into a
`<br />` tag. But this makes things difficult for those who like to `<br />` 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 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 span will cause an unintended line break in the output. Others just
skipping to change at line 6158 skipping to change at line 6174
<p><em>foo<strong>bar</strong>baz</em></p> <p><em>foo<strong>bar</strong>baz</em></p>
```````````````````````````````` ````````````````````````````````
Note that in the preceding case, the interpretation Note that in the preceding case, the interpretation
``` markdown ``` markdown
<p><em>foo</em><em>bar<em></em>baz</em></p> <p><em>foo</em><em>bar<em></em>baz</em></p>
``` ```
is precluded by the condition that a delimiter that is precluded by the condition that a delimiter that
can both open and close (like the `*` after `foo` can both open and close (like the `*` after `foo`)
cannot form emphasis if the sum of the lengths of cannot form emphasis if the sum of the lengths of
the delimiter runs containing the opening and the delimiter runs containing the opening and
closing delimiters is a multiple of 3. closing delimiters is a multiple of 3.
The same condition ensures that the following The same condition ensures that the following
cases are all strong emphasis nested inside cases are all strong emphasis nested inside
emphasis, even when the interior spaces are emphasis, even when the interior spaces are
omitted: omitted:
```````````````````````````````` example ```````````````````````````````` example
skipping to change at line 6186 skipping to change at line 6202
. .
<p><em>foo <strong>bar</strong></em></p> <p><em>foo <strong>bar</strong></em></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
*foo**bar*** *foo**bar***
. .
<p><em>foo<strong>bar</strong></em></p> <p><em>foo<strong>bar</strong></em></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example
*foo**bar***
.
<p><em>foo<strong>bar</strong></em></p>
````````````````````````````````
Indefinite levels of nesting are possible: Indefinite levels of nesting are possible:
```````````````````````````````` example ```````````````````````````````` example
*foo **bar *baz* bim** bop* *foo **bar *baz* bim** bop*
. .
<p><em>foo <strong>bar <em>baz</em> bim</strong> bop</em></p> <p><em>foo <strong>bar <em>baz</em> bim</strong> bop</em></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
*foo [*bar*](/url)* *foo [*bar*](/url)*
skipping to change at line 6871 skipping to change at line 6881
Backslash escapes and entity and numeric character references Backslash escapes and entity and numeric character references
may be used in titles: may be used in titles:
```````````````````````````````` example ```````````````````````````````` example
[link](/url "title \"&quot;") [link](/url "title \"&quot;")
. .
<p><a href="/url" title="title &quot;&quot;">link</a></p> <p><a href="/url" title="title &quot;&quot;">link</a></p>
```````````````````````````````` ````````````````````````````````
Titles must be separated from the link using a [whitespace].
Other [Unicode whitespace] like non-breaking space doesn't work.
```````````````````````````````` example
[link](/url "title")
.
<p><a href="/url%C2%A0%22title%22">link</a></p>
````````````````````````````````
Nested balanced quotes are not allowed without escaping: Nested balanced quotes are not allowed without escaping:
```````````````````````````````` example ```````````````````````````````` example
[link](/url "title "and" title") [link](/url "title "and" title")
. .
<p>[link](/url &quot;title &quot;and&quot; title&quot;)</p> <p>[link](/url &quot;title &quot;and&quot; title&quot;)</p>
```````````````````````````````` ````````````````````````````````
But it is easy to work around this by using a different quote type: But it is easy to work around this by using a different quote type:
skipping to change at line 7477 skipping to change at line 7496
following closing bracket: following closing bracket:
```````````````````````````````` example ```````````````````````````````` example
[foo*]: /url [foo*]: /url
*[foo*] *[foo*]
. .
<p>*<a href="/url">foo*</a></p> <p>*<a href="/url">foo*</a></p>
```````````````````````````````` ````````````````````````````````
Full references take precedence over shortcut references: Full and compact references take precedence over shortcut
references:
```````````````````````````````` example ```````````````````````````````` example
[foo][bar] [foo][bar]
[foo]: /url1 [foo]: /url1
[bar]: /url2 [bar]: /url2
. .
<p><a href="/url2">foo</a></p> <p><a href="/url2">foo</a></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example
[foo][]
[foo]: /url1
.
<p><a href="/url1">foo</a></p>
````````````````````````````````
Inline links also take precedence:
```````````````````````````````` example
[foo]()
[foo]: /url1
.
<p><a href="">foo</a></p>
````````````````````````````````
```````````````````````````````` example
[foo](not a link)
[foo]: /url1
.
<p><a href="/url1">foo</a>(not a link)</p>
````````````````````````````````
In the following case `[bar][baz]` is parsed as a reference, In the following case `[bar][baz]` is parsed as a reference,
`[foo]` as normal text: `[foo]` as normal text:
```````````````````````````````` example ```````````````````````````````` example
[foo][bar][baz] [foo][bar][baz]
[baz]: /url [baz]: /url
. .
<p>[foo]<a href="/url">bar</a></p> <p>[foo]<a href="/url">bar</a></p>
```````````````````````````````` ````````````````````````````````
skipping to change at line 8410 skipping to change at line 8456
1. First we iterate through the open blocks, starting with the 1. First we iterate through the open blocks, starting with the
root document, and descending through last children down to the last root document, and descending through last children down to the last
open block. Each block imposes a condition that the line must satisfy open block. Each block imposes a condition that the line must satisfy
if the block is to remain open. For example, a block quote requires a if the block is to remain open. For example, a block quote requires a
`>` character. A paragraph requires a non-blank line. `>` character. A paragraph requires a non-blank line.
In this phase we may match all or just some of the open In this phase we may match all or just some of the open
blocks. But we cannot close unmatched blocks yet, because we may have a blocks. But we cannot close unmatched blocks yet, because we may have a
[lazy continuation line]. [lazy continuation line].
2. Next, after consuming the continuation markers for existing 2. Next, after consuming the continuation markers for existing
blocks, we look for new block starts (e.g. `>` for a block quote. blocks, we look for new block starts (e.g. `>` for a block quote).
If we encounter a new block start, we close any blocks unmatched If we encounter a new block start, we close any blocks unmatched
in step 1 before creating the new block as a child of the last in step 1 before creating the new block as a child of the last
matched block. matched block.
3. Finally, we look at the remainder of the line (after block 3. Finally, we look at the remainder of the line (after block
markers like `>`, list markers, and indentation have been consumed). markers like `>`, list markers, and indentation have been consumed).
This is text that can be incorporated into the last open This is text that can be incorporated into the last open
block (a paragraph, code block, heading, or raw HTML). block (a paragraph, code block, heading, or raw HTML).
Setext headings are formed when we see a line of a paragraph Setext headings are formed when we see a line of a paragraph
 End of changes. 17 change blocks. 
34 lines changed or deleted 80 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/