spec.txt   spec.txt 
--- ---
title: CommonMark Spec title: CommonMark Spec
author: John MacFarlane author: John MacFarlane
version: 0.25 version: 0.26
date: '2016-03-24' date: '2016-07-15'
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
the first Markdown-to-HTML converter in perl, and it soon became the first Markdown-to-HTML converter in Perl, and it soon became
widely used in websites. By 2014 there were dozens of ubiquitous. In the next decade, dozens of implementations were
implementations in many languages. Some of them extended basic developed in many languages. Some extended the original
Markdown syntax with conventions for footnotes, definition lists, Markdown syntax with conventions for footnotes, tables, and
tables, and other constructs, and some allowed output not just in other document elements. Some allowed Markdown documents to be
HTML but in LaTeX and many other formats. rendered in formats other than HTML. Websites like Reddit,
StackOverflow, and GitHub had millions of people using Markdown.
And Markdown started to be used beyond the web, to author books,
articles, slide shows, letters, and lecture notes.
What distinguishes Markdown from many other lightweight markup
syntaxes, which are often easier to write, is its readability.
As Gruber writes:
> The overriding design goal for Markdown's formatting syntax is
> to make it as readable as possible. The idea is that a
> Markdown-formatted document should be publishable as-is, as
> plain text, without looking like it's been marked up with tags
> or formatting instructions.
> (<http://daringfireball.net/projects/markdown/>)
The point can be illustrated by comparing a sample of
[AsciiDoc](http://www.methods.co.nz/asciidoc/) with
an equivalent sample of Markdown. Here is a sample of
AsciiDoc from the AsciiDoc manual:
```
1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.
2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.
a. This list is nested and does not require explicit item
continuation.
+
This paragraph is part of the preceding list item.
b. List item b.
This paragraph belongs to item two of the outer list.
--
```
And here is the equivalent in Markdown:
```
1. List item one.
List item one continued with a second paragraph followed by an
Indented block.
$ ls *.sh
$ mv *.sh ~/tmp
List item continued with a third paragraph.
2. List item two continued with an open block.
This paragraph is part of the preceding list item.
1. This list is nested and does not require explicit item continuation.
This paragraph is part of the preceding list item.
2. List item b.
This paragraph belongs to item two of the outer list.
```
The AsciiDoc version is, arguably, easier to write. You don't need
to worry about indentation. But the Markdown version is much easier
to read. The nesting of list items is apparent to the eye in the
source, not just in the processed document.
## Why is a spec needed? ## Why is a spec needed?
John Gruber's [canonical description of Markdown's John Gruber's [canonical description of Markdown's
syntax](http://daringfireball.net/projects/markdown/syntax) syntax](http://daringfireball.net/projects/markdown/syntax)
does not specify the syntax unambiguously. Here are some examples of does not specify the syntax unambiguously. Here are some examples of
questions it does not answer: questions it does not answer:
1. How much indentation is needed for a sublist? The spec says that 1. How much indentation is needed for a sublist? The spec says that
continuation paragraphs need to be indented four spaces, but is continuation paragraphs need to be indented four spaces, but is
skipping to change at line 261 skipping to change at line 339
`*`, `+`, `,`, `-`, `.`, `/`, `:`, `;`, `<`, `=`, `>`, `?`, `@`, `*`, `+`, `,`, `-`, `.`, `/`, `:`, `;`, `<`, `=`, `>`, `?`, `@`,
`[`, `\`, `]`, `^`, `_`, `` ` ``, `{`, `|`, `}`, or `~`. `[`, `\`, `]`, `^`, `_`, `` ` ``, `{`, `|`, `}`, or `~`.
A [punctuation character](@) is an [ASCII A [punctuation character](@) is an [ASCII
punctuation character] or anything in punctuation character] or anything in
the Unicode classes `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`. the Unicode classes `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`.
## Tabs ## Tabs
Tabs in lines are not expanded to [spaces]. However, Tabs in lines are not expanded to [spaces]. However,
in contexts where indentation is significant for the in contexts where whitespace helps to define block structure,
document's structure, tabs behave as if they were replaced tabs behave as if they were replaced by spaces with a tab stop
by spaces with a tab stop of 4 characters. of 4 characters.
Thus, for example, a tab can be used instead of four spaces
in an indented code block. (Note, however, that internal
tabs are passed through as literal tabs, not expanded to
spaces.)
```````````````````````````````` example ```````````````````````````````` example
→foo→baz→→bim →foo→baz→→bim
. .
<pre><code>foo→baz→→bim <pre><code>foo→baz→→bim
</code></pre> </code></pre>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
→foo→baz→→bim →foo→baz→→bim
skipping to change at line 288 skipping to change at line 371
```````````````````````````````` example ```````````````````````````````` example
a→a a→a
ὐ→a ὐ→a
. .
<pre><code>a→a <pre><code>a→a
ὐ→a ὐ→a
</code></pre> </code></pre>
```````````````````````````````` ````````````````````````````````
In the following example, a continuation paragraph of a list
item is indented with a tab; this has exactly the same effect
as indentation with four spaces would:
```````````````````````````````` example ```````````````````````````````` example
- foo - foo
→bar →bar
. .
<ul> <ul>
<li> <li>
<p>foo</p> <p>foo</p>
<p>bar</p> <p>bar</p>
</li> </li>
skipping to change at line 315 skipping to change at line 402
. .
<ul> <ul>
<li> <li>
<p>foo</p> <p>foo</p>
<pre><code> bar <pre><code> bar
</code></pre> </code></pre>
</li> </li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
Normally the `>` that begins a block quote may be followed
optionally by a space, which is not considered part of the
content. In the following case `>` is followed by a tab,
which is treated as if it were expanded into spaces.
Since one of theses spaces is considered part of the
delimiter, `foo` is considered to be indented six spaces
inside the block quote context, so we get an indented
code block starting with two spaces.
```````````````````````````````` example ```````````````````````````````` example
>→→foo >→→foo
. .
<blockquote> <blockquote>
<pre><code> foo <pre><code> foo
</code></pre> </code></pre>
</blockquote> </blockquote>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
skipping to change at line 362 skipping to change at line 458
<li>bar <li>bar
<ul> <ul>
<li>baz</li> <li>baz</li>
</ul> </ul>
</li> </li>
</ul> </ul>
</li> </li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example
#→Foo
.
<h1>Foo</h1>
````````````````````````````````
```````````````````````````````` example
*→*→*→
.
<hr />
````````````````````````````````
## Insecure characters ## Insecure characters
For security reasons, the Unicode character `U+0000` must be replaced For security reasons, the Unicode character `U+0000` must be replaced
with the REPLACEMENT CHARACTER (`U+FFFD`). with the REPLACEMENT CHARACTER (`U+FFFD`).
# Blocks and inlines # Blocks and inlines
We can think of a document as a sequence of We can think of a document as a sequence of
[blocks](@)---structural elements like paragraphs, block [blocks](@)---structural elements like paragraphs, block
quotations, lists, headings, rules, and code blocks. Some blocks (like quotations, lists, headings, rules, and code blocks. Some blocks (like
skipping to change at line 675 skipping to change at line 783
```````````````````````````````` example ```````````````````````````````` example
#5 bolt #5 bolt
#hashtag #hashtag
. .
<p>#5 bolt</p> <p>#5 bolt</p>
<p>#hashtag</p> <p>#hashtag</p>
```````````````````````````````` ````````````````````````````````
A tab will not work:
```````````````````````````````` example
#→foo
.
<p>#→foo</p>
````````````````````````````````
This is not a heading, because the first `#` is escaped: This is not a heading, because the first `#` is escaped:
```````````````````````````````` example ```````````````````````````````` example
\## foo \## foo
. .
<p>## foo</p> <p>## foo</p>
```````````````````````````````` ````````````````````````````````
Contents are parsed as inlines: Contents are parsed as inlines:
skipping to change at line 1772 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, if no line is encountered that meets the the document or other [container block](@), if no line is encountered that meets the
[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 2085 skipping to change at line 2185
A pre tag (type 1): A pre tag (type 1):
```````````````````````````````` example ```````````````````````````````` example
<pre language="haskell"><code> <pre language="haskell"><code>
import Text.HTML.TagSoup import Text.HTML.TagSoup
main :: IO () main :: IO ()
main = print $ parseTags tags main = print $ parseTags tags
</code></pre> </code></pre>
okay
. .
<pre language="haskell"><code> <pre language="haskell"><code>
import Text.HTML.TagSoup import Text.HTML.TagSoup
main :: IO () main :: IO ()
main = print $ parseTags tags main = print $ parseTags tags
</code></pre> </code></pre>
<p>okay</p>
```````````````````````````````` ````````````````````````````````
A script tag (type 1): A script tag (type 1):
```````````````````````````````` example ```````````````````````````````` example
<script type="text/javascript"> <script type="text/javascript">
// JavaScript example // JavaScript example
document.getElementById("demo").innerHTML = "Hello JavaScript!"; document.getElementById("demo").innerHTML = "Hello JavaScript!";
</script> </script>
okay
. .
<script type="text/javascript"> <script type="text/javascript">
// JavaScript example // JavaScript example
document.getElementById("demo").innerHTML = "Hello JavaScript!"; document.getElementById("demo").innerHTML = "Hello JavaScript!";
</script> </script>
<p>okay</p>
```````````````````````````````` ````````````````````````````````
A style tag (type 1): A style tag (type 1):
```````````````````````````````` example ```````````````````````````````` example
<style <style
type="text/css"> type="text/css">
h1 {color:red;} h1 {color:red;}
p {color:blue;} p {color:blue;}
</style> </style>
okay
. .
<style <style
type="text/css"> type="text/css">
h1 {color:red;} h1 {color:red;}
p {color:blue;} p {color:blue;}
</style> </style>
<p>okay</p>
```````````````````````````````` ````````````````````````````````
If there is no matching end tag, the block will end at the If there is no matching end tag, the block will end at the
end of the document (or the enclosing [block quote][block quotes] end of the document (or the enclosing [block quote][block quotes]
or [list item][list items]): or [list item][list items]):
```````````````````````````````` example ```````````````````````````````` example
<style <style
type="text/css"> type="text/css">
skipping to change at line 2207 skipping to change at line 2313
</script>1. *bar* </script>1. *bar*
```````````````````````````````` ````````````````````````````````
A comment (type 2): A comment (type 2):
```````````````````````````````` example ```````````````````````````````` example
<!-- Foo <!-- Foo
bar bar
baz --> baz -->
okay
. .
<!-- Foo <!-- Foo
bar bar
baz --> baz -->
<p>okay</p>
```````````````````````````````` ````````````````````````````````
A processing instruction (type 3): A processing instruction (type 3):
```````````````````````````````` example ```````````````````````````````` example
<?php <?php
echo '>'; echo '>';
?> ?>
okay
. .
<?php <?php
echo '>'; echo '>';
?> ?>
<p>okay</p>
```````````````````````````````` ````````````````````````````````
A declaration (type 4): A declaration (type 4):
```````````````````````````````` example ```````````````````````````````` example
<!DOCTYPE html> <!DOCTYPE html>
. .
<!DOCTYPE html> <!DOCTYPE html>
```````````````````````````````` ````````````````````````````````
skipping to change at line 2253 skipping to change at line 2363
{ {
if (a < b && a < 0) then { if (a < b && a < 0) then {
return 1; return 1;
} else { } else {
return 0; return 0;
} }
} }
]]> ]]>
okay
. .
<![CDATA[ <![CDATA[
function matchwo(a,b) function matchwo(a,b)
{ {
if (a < b && a < 0) then { if (a < b && a < 0) then {
return 1; return 1;
} else { } else {
return 0; return 0;
} }
} }
]]> ]]>
<p>okay</p>
```````````````````````````````` ````````````````````````````````
The opening tag can be indented 1-3 spaces, but not 4: The opening tag can be indented 1-3 spaces, but not 4:
```````````````````````````````` example ```````````````````````````````` example
<!-- foo --> <!-- foo -->
<!-- foo --> <!-- foo -->
. .
<!-- foo --> <!-- foo -->
skipping to change at line 2958 skipping to change at line 3070
> # Foo > # Foo
> bar > bar
> baz > baz
. .
<pre><code>&gt; # Foo <pre><code>&gt; # Foo
&gt; bar &gt; bar
&gt; baz &gt; baz
</code></pre> </code></pre>
```````````````````````````````` ````````````````````````````````
The Laziness clause allows us to omit the `>` before a The Laziness clause allows us to omit the `>` before
paragraph continuation line: [paragraph continuation text]:
```````````````````````````````` example ```````````````````````````````` example
> # Foo > # Foo
> bar > bar
baz baz
. .
<blockquote> <blockquote>
<h1>Foo</h1> <h1>Foo</h1>
<p>bar <p>bar
baz</p> baz</p>
skipping to change at line 3059 skipping to change at line 3171
foo foo
``` ```
. .
<blockquote> <blockquote>
<pre><code></code></pre> <pre><code></code></pre>
</blockquote> </blockquote>
<p>foo</p> <p>foo</p>
<pre><code></code></pre> <pre><code></code></pre>
```````````````````````````````` ````````````````````````````````
Note that in the following case, we have a paragraph Note that in the following case, we have a [lazy
continuation line: continuation line]:
```````````````````````````````` example ```````````````````````````````` example
> foo > foo
- bar - bar
. .
<blockquote> <blockquote>
<p>foo <p>foo
- bar</p> - bar</p>
</blockquote> </blockquote>
```````````````````````````````` ````````````````````````````````
To see why, note that in To see why, note that in
```markdown ```markdown
> foo > foo
> - bar > - bar
``` ```
the `- bar` is indented too far to start a list, and can't the `- bar` is indented too far to start a list, and can't
be an indented code block because indented code blocks cannot be an indented code block because indented code blocks cannot
interrupt paragraphs, so it is a [paragraph continuation line]. interrupt paragraphs, so it is [paragraph continuation text].
A block quote can be empty: A block quote can be empty:
```````````````````````````````` example ```````````````````````````````` example
> >
. .
<blockquote> <blockquote>
</blockquote> </blockquote>
```````````````````````````````` ````````````````````````````````
skipping to change at line 3295 skipping to change at line 3407
is a sequence of 1--9 arabic digits (`0-9`), followed by either a is a sequence of 1--9 arabic digits (`0-9`), followed by either a
`.` character or a `)` character. (The reason for the length `.` character or a `)` character. (The reason for the length
limit is that with 10 digits we start seeing integer overflows limit is that with 10 digits we start seeing integer overflows
in some browsers.) in some browsers.)
The following rules define [list items]: The following rules define [list items]:
1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of 1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of
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 0 < *N* < 5 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
is, when it starts on a line that would otherwise count as
[paragraph continuation text]---then (a) the lines *Ls* must
not begin with a blank line, and (b) if 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 3468 skipping to change at line 3586
```````````````````````````````` example ```````````````````````````````` example
-one -one
2.two 2.two
. .
<p>-one</p> <p>-one</p>
<p>2.two</p> <p>2.two</p>
```````````````````````````````` ````````````````````````````````
A list item may not contain blocks that are separated by more than A list item may contain blocks that are separated by more than
one blank line. Thus, two blank lines will end a list, unless the one blank line.
two blanks are contained in a [fenced code block].
```````````````````````````````` example ```````````````````````````````` example
- foo - foo
bar bar
- foo
bar
- ```
foo
bar
```
- baz
+ ```
foo
bar
```
. .
<ul> <ul>
<li> <li>
<p>foo</p> <p>foo</p>
<p>bar</p> <p>bar</p>
</li> </li>
<li>
<p>foo</p>
</li>
</ul>
<p>bar</p>
<ul>
<li>
<pre><code>foo
bar
</code></pre>
</li>
<li>
<p>baz</p>
<ul>
<li>
<pre><code>foo
bar
</code></pre>
</li>
</ul>
</li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
A list item may contain any kind of block: A list item may contain any kind of block:
```````````````````````````````` example ```````````````````````````````` example
1. foo 1. foo
``` ```
bar bar
skipping to change at line 3553 skipping to change at line 3629
</code></pre> </code></pre>
<p>baz</p> <p>baz</p>
<blockquote> <blockquote>
<p>bam</p> <p>bam</p>
</blockquote> </blockquote>
</li> </li>
</ol> </ol>
```````````````````````````````` ````````````````````````````````
A list item that contains an indented code block will preserve A list item that contains an indented code block will preserve
empty lines within the code block verbatim, unless there are two empty lines within the code block verbatim.
or more empty lines in a row (since as described above, two
blank lines end the list):
```````````````````````````````` example ```````````````````````````````` example
- Foo - Foo
bar bar
baz baz
. .
<ul> <ul>
<li> <li>
<p>Foo</p> <p>Foo</p>
<pre><code>bar <pre><code>bar
baz baz
</code></pre> </code></pre>
</li> </li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example
- Foo
bar
baz
.
<ul>
<li>
<p>Foo</p>
<pre><code>bar
</code></pre>
</li>
</ul>
<pre><code> baz
</code></pre>
````````````````````````````````
Note that ordered list start numbers must be nine digits or less: Note that ordered list start numbers must be nine digits or less:
```````````````````````````````` example ```````````````````````````````` example
123456789. ok 123456789. ok
. .
<ol start="123456789"> <ol start="123456789">
<li>ok</li> <li>ok</li>
</ol> </ol>
```````````````````````````````` ````````````````````````````````
skipping to change at line 3821 skipping to change at line 3877
<pre><code>bar <pre><code>bar
</code></pre> </code></pre>
</li> </li>
<li> <li>
<pre><code>baz <pre><code>baz
</code></pre> </code></pre>
</li> </li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
When the list item starts with a blank line, the number of spaces
following the list marker doesn't change the required indentation:
```````````````````````````````` example
-
foo
.
<ul>
<li>foo</li>
</ul>
````````````````````````````````
A list item can begin with at most one blank line. A list item can begin with at most one blank line.
In the following example, `foo` is not part of the list In the following example, `foo` is not part of the list
item: item:
```````````````````````````````` example ```````````````````````````````` example
- -
foo foo
. .
<ul> <ul>
skipping to change at line 3888 skipping to change at line 3956
A list may start or end with an empty list item: A list may start or end with an empty list item:
```````````````````````````````` example ```````````````````````````````` example
* *
. .
<ul> <ul>
<li></li> <li></li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
However, an empty list item cannot interrupt a paragraph:
```````````````````````````````` example
foo
*
foo
1.
.
<p>foo
*</p>
<p>foo
1.</p>
````````````````````````````````
4. **Indentation.** If a sequence of lines *Ls* constitutes a list item 4. **Indentation.** If a sequence of lines *Ls* constitutes a list item
according to rule #1, #2, or #3, then the result of indenting each line according to rule #1, #2, or #3, then the result of indenting each line
of *Ls* by 1-3 spaces (the same for each line) also constitutes a of *Ls* by 1-3 spaces (the same for each line) also constitutes a
list item with the same contents and attributes. If a line is list item with the same contents and attributes. If a line is
empty, then it need not be indented. empty, then it need not be indented.
Indented one space: Indented one space:
```````````````````````````````` example ```````````````````````````````` example
1. A paragraph 1. A paragraph
skipping to change at line 4073 skipping to change at line 4156
The rules for sublists follow from the general rules above. A sublist 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 must be indented the same number of spaces a paragraph would need to be
in order to be included in the list item. in order to be included in the list item.
So, in this case we need two spaces indent: So, in this case we need two spaces indent:
```````````````````````````````` example ```````````````````````````````` example
- foo - foo
- bar - bar
- baz - baz
- boo
. .
<ul> <ul>
<li>foo <li>foo
<ul> <ul>
<li>bar <li>bar
<ul> <ul>
<li>baz</li> <li>baz
<ul>
<li>boo</li>
</ul>
</li>
</ul> </ul>
</li> </li>
</ul> </ul>
</li> </li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
One is not enough: One is not enough:
```````````````````````````````` example ```````````````````````````````` example
- foo - foo
- bar - bar
- baz - baz
- boo
. .
<ul> <ul>
<li>foo</li> <li>foo</li>
<li>bar</li> <li>bar</li>
<li>baz</li> <li>baz</li>
<li>boo</li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
Here we need four, because the list marker is wider: Here we need four, because the list marker is wider:
```````````````````````````````` example ```````````````````````````````` example
10) foo 10) foo
- bar - bar
. .
<ol start="10"> <ol start="10">
skipping to change at line 4445 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:
```````````````````````````````` example ```````````````````````````````` 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.
.
<p>The number of windows in my house is</p>
<ol start="14">
<li>The number of doors is 6.</li>
</ol>
```````````````````````````````` ````````````````````````````````
Oddly, though, `Markdown.pl` *does* allow a blockquote to
interrupt a paragraph, even though the same considerations might
apply.
Oddly, `Markdown.pl` *does* allow a blockquote to interrupt a paragraph, In CommonMark, we do allow lists to interrupt paragraphs, for
even though the same considerations might apply. We think that the two two reasons. First, it is natural and not uncommon for people
cases should be treated the same. Here are two reasons for allowing to start lists without blank lines:
lists to interrupt paragraphs:
First, it is natural and not uncommon for people to start lists without
blank lines:
I need to buy I need to buy
- new shoes - new shoes
- a coat - a coat
- a plane ticket - 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
skipping to change at line 4495 skipping to change at line 4579
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 I need to buy
- new shoes - new shoes
- a coat - a coat
- a plane ticket - 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.
Our adherence to the [principle of uniformity] Since it is well established Markdown practice to allow lists to
thus inclines us to think that there are two coherent packages: interrupt paragraphs inside list items, the [principle of
uniformity] requires us to allow this outside list items as
well. ([reStructuredText](http://docutils.sourceforge.net/rst.html)
takes a different approach, requiring blank lines before lists
even inside other list items.)
1. Require blank lines before *all* lists and blockquotes, In order to solve of unwanted lists in paragraphs with
including lists that occur as sublists inside other list items. hard-wrapped numerals, we allow only lists starting with `1` to
interrupt paragraphs. Thus,
2. Require blank lines in none of these places. ```````````````````````````````` example
The number of windows in my house is
14. The number of doors is 6.
.
<p>The number of windows in my house is
14. The number of doors is 6.</p>
````````````````````````````````
[reStructuredText](http://docutils.sourceforge.net/rst.html) takes We may still get an unintended result in cases like
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 ```````````````````````````````` example
a list: The number of windows in my house is
1. The number of doors is 6.
.
<p>The number of windows in my house is</p>
<ol>
<li>The number of doors is 6.</li>
</ol>
````````````````````````````````
but this rule should prevent most spurious list captures.
There can be any number of blank lines between items:
```````````````````````````````` example ```````````````````````````````` example
- foo - foo
- bar - bar
- baz - baz
. .
<ul> <ul>
<li> <li>
<p>foo</p> <p>foo</p>
</li> </li>
<li> <li>
<p>bar</p> <p>bar</p>
</li> </li>
</ul> <li>
<ul> <p>baz</p>
<li>baz</li> </li>
</ul>
````````````````````````````````
As illustrated above in the section on [list items],
two blank lines between blocks *within* a list item will also end a
list:
```````````````````````````````` example
- foo
bar
- baz
.
<ul>
<li>foo</li>
</ul>
<p>bar</p>
<ul>
<li>baz</li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
Indeed, two blank lines will end *all* containing lists:
```````````````````````````````` example ```````````````````````````````` example
- foo - foo
- bar - bar
- baz - baz
bim bim
. .
<ul> <ul>
<li>foo <li>foo
<ul> <ul>
<li>bar <li>bar
<ul> <ul>
<li>baz</li> <li>
<p>baz</p>
<p>bim</p>
</li>
</ul> </ul>
</li> </li>
</ul> </ul>
</li> </li>
</ul> </ul>
<pre><code> bim
</code></pre>
```````````````````````````````` ````````````````````````````````
Thus, two blank lines can be used to separate consecutive lists of To separate consecutive lists of the same type, or to separate a
the same type, or to separate a list from an indented code block list from an indented code block that would otherwise be parsed
that would otherwise be parsed as a subparagraph of the final list as a subparagraph of the final list item, you can insert a blank HTML
item: comment:
```````````````````````````````` example ```````````````````````````````` example
- foo - foo
- bar - bar
<!-- -->
- baz - baz
- bim - bim
. .
<ul> <ul>
<li>foo</li> <li>foo</li>
<li>bar</li> <li>bar</li>
</ul> </ul>
<!-- -->
<ul> <ul>
<li>baz</li> <li>baz</li>
<li>bim</li> <li>bim</li>
</ul> </ul>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
- foo - foo
notcode notcode
- foo - foo
<!-- -->
code code
. .
<ul> <ul>
<li> <li>
<p>foo</p> <p>foo</p>
<p>notcode</p> <p>notcode</p>
</li> </li>
<li> <li>
<p>foo</p> <p>foo</p>
</li> </li>
</ul> </ul>
<!-- -->
<pre><code>code <pre><code>code
</code></pre> </code></pre>
```````````````````````````````` ````````````````````````````````
List items need not be indented to the same level. The following List items need not be indented to the same level. The following
list items will be treated as items at the same list level, list items will be treated as items at the same list level,
since none is indented enough to belong to the previous list since none is indented enough to belong to the previous list
item: item:
```````````````````````````````` example ```````````````````````````````` example
skipping to change at line 5499 skipping to change at line 5589
iff it is part of a [right-flanking delimiter run]. iff it is part of a [right-flanking delimiter run].
8. A double `__` [can close strong emphasis] 8. A double `__` [can close strong emphasis]
it is part of a [right-flanking delimiter run] it is part of a [right-flanking delimiter run]
and either (a) not part of a [left-flanking delimiter run] and either (a) not part of a [left-flanking delimiter run]
or (b) part of a [left-flanking delimiter run] or (b) part of a [left-flanking delimiter run]
followed by punctuation. followed by punctuation.
9. Emphasis begins with a delimiter that [can open emphasis] and ends 9. Emphasis begins with a delimiter that [can open emphasis] and ends
with a delimiter that [can close emphasis], and that uses the same with a delimiter that [can close emphasis], and that uses the same
character (`_` or `*`) as the opening delimiter. There must character (`_` or `*`) as the opening delimiter. The
be a nonempty sequence of inlines between the open delimiter opening and closing delimiters must belong to separate
and the closing delimiter; these form the contents of the emphasis [delimiter runs]. If one of the delimiters can both
inline. 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.
10. Strong emphasis begins with a delimiter that 10. Strong emphasis begins with a delimiter that
[can open strong emphasis] and ends with a delimiter that [can open strong emphasis] and ends with a delimiter that
[can close strong emphasis], and that uses the same character [can close strong emphasis], and that uses the same character
(`_` or `*`) as the opening delimiter. (`_` or `*`) as the opening delimiter. The
There must be a nonempty sequence of inlines between the open opening and closing delimiters must belong to separate
delimiter and the closing delimiter; these form the contents of [delimiter runs]. If one of the delimiters can both open
the strong emphasis inline. 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.
11. A literal `*` character cannot occur at the beginning or end of 11. A literal `*` character cannot occur at the beginning or end of
`*`-delimited emphasis or `**`-delimited strong emphasis, unless it `*`-delimited emphasis or `**`-delimited strong emphasis, unless it
is backslash-escaped. is backslash-escaped.
12. A literal `_` character cannot occur at the beginning or end of 12. A literal `_` character cannot occur at the beginning or end of
`_`-delimited emphasis or `__`-delimited strong emphasis, unless it `_`-delimited emphasis or `__`-delimited strong emphasis, unless it
is backslash-escaped. is backslash-escaped.
Where rules 1--12 above are compatible with multiple parsings, Where rules 1--12 above are compatible with multiple parsings,
skipping to change at line 5534 skipping to change at line 5628
an interpretation `<strong>...</strong>` is always preferred to an interpretation `<strong>...</strong>` is always preferred to
`<em><em>...</em></em>`. `<em><em>...</em></em>`.
14. An interpretation `<strong><em>...</em></strong>` is always 14. An interpretation `<strong><em>...</em></strong>` is always
preferred to `<em><strong>..</strong></em>`. preferred to `<em><strong>..</strong></em>`.
15. When two potential emphasis or strong emphasis spans overlap, 15. When two potential emphasis or strong emphasis spans overlap,
so that the second begins before the first ends and ends after so that the second begins before the first ends and ends after
the first ends, the first takes precedence. Thus, for example, the first ends, the first takes precedence. Thus, for example,
`*foo _bar* baz_` is parsed as `<em>foo _bar</em> baz_` rather `*foo _bar* baz_` is parsed as `<em>foo _bar</em> baz_` rather
than `*foo <em>bar* baz</em>`. For the same reason, than `*foo <em>bar* baz</em>`.
`**foo*bar**` is parsed as `<em><em>foo</em>bar</em>*`
rather than `<strong>foo*bar</strong>`.
16. When there are two potential emphasis or strong emphasis spans 16. When there are two potential emphasis or strong emphasis spans
with the same closing delimiter, the shorter one (the one that with the same closing delimiter, the shorter one (the one that
opens later) takes precedence. Thus, for example, opens later) takes precedence. Thus, for example,
`**foo **bar baz**` is parsed as `**foo <strong>bar baz</strong>` `**foo **bar baz**` is parsed as `**foo <strong>bar baz</strong>`
rather than `<strong>foo **bar baz</strong>`. rather than `<strong>foo **bar baz</strong>`.
17. Inline code spans, links, images, and HTML tags group more tightly 17. Inline code spans, links, images, and HTML tags group more tightly
than emphasis. So, when there is a choice between an interpretation than emphasis. So, when there is a choice between an interpretation
that contains one of these elements and one that does not, the that contains one of these elements and one that does not, the
skipping to change at line 5693 skipping to change at line 5785
. .
<p>*foo bar *</p> <p>*foo bar *</p>
```````````````````````````````` ````````````````````````````````
A newline also counts as whitespace: A newline also counts as whitespace:
```````````````````````````````` example ```````````````````````````````` example
*foo bar *foo bar
* *
. .
<p>*foo bar</p> <p>*foo bar
<ul> *</p>
<li></li>
</ul>
```````````````````````````````` ````````````````````````````````
This is not emphasis, because the second `*` is This is not emphasis, because the second `*` is
preceded by punctuation and followed by an alphanumeric preceded by punctuation and followed by an alphanumeric
(hence it is not part of a [right-flanking delimiter run]: (hence it is not part of a [right-flanking delimiter run]:
```````````````````````````````` example ```````````````````````````````` example
*(*foo) *(*foo)
. .
<p>*(*foo)</p> <p>*(*foo)</p>
skipping to change at line 6055 skipping to change at line 6145
. .
<p><em>foo <em>bar</em></em></p> <p><em>foo <em>bar</em></em></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
*foo **bar** baz* *foo **bar** baz*
. .
<p><em>foo <strong>bar</strong> baz</em></p> <p><em>foo <strong>bar</strong> baz</em></p>
```````````````````````````````` ````````````````````````````````
But note:
```````````````````````````````` example ```````````````````````````````` example
*foo**bar**baz* *foo**bar**baz*
. .
<p><em>foo</em><em>bar</em><em>baz</em></p> <p><em>foo<strong>bar</strong>baz</em></p>
```````````````````````````````` ````````````````````````````````
The difference is that in the preceding case, the internal delimiters Note that in the preceding case, the interpretation
[can close emphasis], while in the cases with spaces, they cannot.
``` markdown
<p><em>foo</em><em>bar<em></em>baz</em></p>
```
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.
The same condition ensures that the following
cases are all strong emphasis nested inside
emphasis, even when the interior spaces are
omitted:
```````````````````````````````` example ```````````````````````````````` example
***foo** bar* ***foo** bar*
. .
<p><em><strong>foo</strong> bar</em></p> <p><em><strong>foo</strong> bar</em></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
*foo **bar*** *foo **bar***
. .
<p><em>foo <strong>bar</strong></em></p> <p><em>foo <strong>bar</strong></em></p>
```````````````````````````````` ````````````````````````````````
Note, however, that in the following case we get no strong ```````````````````````````````` example
emphasis, because the opening delimiter is closed by the first *foo**bar***
`*` before `bar`: .
<p><em>foo<strong>bar</strong></em></p>
````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
*foo**bar*** *foo**bar***
. .
<p><em>foo</em><em>bar</em>**</p> <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>
```````````````````````````````` ````````````````````````````````
skipping to change at line 6168 skipping to change at line 6272
. .
<p><strong>foo <strong>bar</strong></strong></p> <p><strong>foo <strong>bar</strong></strong></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
**foo *bar* baz** **foo *bar* baz**
. .
<p><strong>foo <em>bar</em> baz</strong></p> <p><strong>foo <em>bar</em> baz</strong></p>
```````````````````````````````` ````````````````````````````````
But note:
```````````````````````````````` example ```````````````````````````````` example
**foo*bar*baz** **foo*bar*baz**
. .
<p><em><em>foo</em>bar</em>baz**</p> <p><strong>foo<em>bar</em>baz</strong></p>
```````````````````````````````` ````````````````````````````````
The difference is that in the preceding case, the internal delimiters
[can close emphasis], while in the cases with spaces, they cannot.
```````````````````````````````` example ```````````````````````````````` example
***foo* bar** ***foo* bar**
. .
<p><strong><em>foo</em> bar</strong></p> <p><strong><em>foo</em> bar</strong></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
**foo *bar*** **foo *bar***
. .
<p><strong>foo <em>bar</em></strong></p> <p><strong>foo <em>bar</em></strong></p>
skipping to change at line 6451 skipping to change at line 6550
Rule 15: Rule 15:
```````````````````````````````` example ```````````````````````````````` example
*foo _bar* baz_ *foo _bar* baz_
. .
<p><em>foo _bar</em> baz_</p> <p><em>foo _bar</em> baz_</p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
**foo*bar**
.
<p><em><em>foo</em>bar</em>*</p>
````````````````````````````````
```````````````````````````````` example
*foo __bar *baz bim__ bam* *foo __bar *baz bim__ bam*
. .
<p><em>foo <strong>bar *baz bim</strong> bam</em></p> <p><em>foo <strong>bar *baz bim</strong> bam</em></p>
```````````````````````````````` ````````````````````````````````
Rule 16: Rule 16:
```````````````````````````````` example ```````````````````````````````` example
**foo **bar baz** **foo **bar baz**
. .
skipping to change at line 7306 skipping to change at line 7399
. .
<p><a href="/url" title="title">foo</a> <p><a href="/url" title="title">foo</a>
[]</p> []</p>
```````````````````````````````` ````````````````````````````````
A [shortcut reference link](@) A [shortcut reference link](@)
consists of a [link label] that [matches] a consists of a [link label] that [matches] a
[link reference definition] elsewhere in the [link reference definition] elsewhere in the
document and is not followed by `[]` or a link label. document and is not followed by `[]` or a link label.
The contents of the first link label are parsed as inlines, The contents of the first link label are parsed as inlines,
which are used as the link's text. the link's URI and title which are used as the link's text. The link's URI and title
are provided by the matching link reference definition. are provided by the matching link reference definition.
Thus, `[foo]` is equivalent to `[foo][]`. Thus, `[foo]` is equivalent to `[foo][]`.
```````````````````````````````` example ```````````````````````````````` example
[foo] [foo]
[foo]: /url "title" [foo]: /url "title"
. .
<p><a href="/url" title="title">foo</a></p> <p><a href="/url" title="title">foo</a></p>
```````````````````````````````` ````````````````````````````````
skipping to change at line 8191 skipping to change at line 8284
```````````````````````````````` example ```````````````````````````````` example
### foo ### foo
. .
<h3>foo</h3> <h3>foo</h3>
```````````````````````````````` ````````````````````````````````
## Soft line breaks ## Soft line breaks
A regular line break (not in a code span or HTML tag) that is not A regular line break (not in a code span or HTML tag) that is not
preceded by two or more spaces or a backslash is parsed as a preceded by two or more spaces or a backslash is parsed as a
softbreak. (A softbreak may be rendered in HTML either as a [softbreak](@). (A softbreak may be rendered in HTML either as a
[line ending] or as a space. The result will be the same in [line ending] or as a space. The result will be the same in
browsers. In the examples here, a [line ending] will be used.) browsers. In the examples here, a [line ending] will be used.)
```````````````````````````````` example ```````````````````````````````` example
foo foo
baz baz
. .
<p>foo <p>foo
baz</p> baz</p>
```````````````````````````````` ````````````````````````````````
 End of changes. 69 change blocks. 
184 lines changed or deleted 277 lines changed or added

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