spec.txt   spec.txt 
--- ---
title: CommonMark Spec title: CommonMark Spec
author: John MacFarlane author: John MacFarlane
version: 0.17 version: 0.18
date: 2015-01-24 date: 2015-03-03
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 228 skipping to change at line 228
For security reasons, a conforming parser must strip or replace the For security reasons, a conforming parser must strip or replace the
Unicode character `U+0000`. Unicode character `U+0000`.
A line containing no characters, or a line containing only spaces A line containing no characters, or a line containing only spaces
(`U+0020`) or tabs (`U+0009`), is called a [blank line](@blank-line). (`U+0020`) or tabs (`U+0009`), is called a [blank line](@blank-line).
The following definitions of character classes will be used in this spec: The following definitions of character classes will be used in this spec:
A [whitespace character](@whitespace-character) is a space A [whitespace character](@whitespace-character) is a space
(`U+0020`), tab (`U+0009`), carriage return (`U+000D`), or (`U+0020`), tab (`U+0009`), newline (`U+000A`), line tabulation (`U+000B`),
newline (`U+000A`). form feed (`U+000C`), or carriage return (`U+000D`).
[Whitespace](@whitespace) is a sequence of one or more [whitespace [Whitespace](@whitespace) is a sequence of one or more [whitespace
character]s. character]s.
A [unicode whitespace character](@unicode-whitespace-character) is A [unicode whitespace character](@unicode-whitespace-character) is
any code point in the unicode `Zs` class, or a tab (`U+0009`), any code point in the unicode `Zs` class, or a tab (`U+0009`),
carriage return (`U+000D`), newline (`U+000A`), or form feed carriage return (`U+000D`), newline (`U+000A`), or form feed
(`U+000C`). (`U+000C`).
[Unicode whitespace](@unicode-whitespace) is a sequence of one [Unicode whitespace](@unicode-whitespace) is a sequence of one
skipping to change at line 1847 skipping to change at line 1847
. .
[Foo bar]: [Foo bar]:
<my url> <my url>
'title' 'title'
[Foo bar] [Foo bar]
. .
<p><a href="my%20url" title="title">Foo bar</a></p> <p><a href="my%20url" title="title">Foo bar</a></p>
. .
The title may extend over multiple lines:
.
[foo]: /url '
title
line1
line2
'
[foo]
.
<p><a href="/url" title="
title
line1
line2
">foo</a></p>
.
However, it may not contain a [blank line]:
.
[foo]: /url 'title
with blank line'
[foo]
.
<p>[foo]: /url 'title</p>
<p>with blank line'</p>
<p>[foo]</p>
.
The title may be omitted: The title may be omitted:
. .
[foo]: [foo]:
/url /url
[foo] [foo]
. .
<p><a href="/url">foo</a></p> <p><a href="/url">foo</a></p>
. .
skipping to change at line 1918 skipping to change at line 1950
. .
Here is a link reference definition with no corresponding link. Here is a link reference definition with no corresponding link.
It contributes nothing to the document. It contributes nothing to the document.
. .
[foo]: /url [foo]: /url
. .
. .
Here is another one:
.
[
foo
]: /url
bar
.
<p>bar</p>
.
This is not a link reference definition, because there are This is not a link reference definition, because there are
[non-space character]s after the title: [non-space character]s after the title:
. .
[foo]: /url "title" ok [foo]: /url "title" ok
. .
<p>[foo]: /url &quot;title&quot; ok</p> <p>[foo]: /url &quot;title&quot; ok</p>
. .
This is not a link reference definition, because it is indented This is not a link reference definition, because it is indented
skipping to change at line 2691 skipping to change at line 2734
<blockquote> <blockquote>
<blockquote> <blockquote>
<ul> <ul>
<li>one</li> <li>one</li>
</ul> </ul>
<p>two</p> <p>two</p>
</blockquote> </blockquote>
</blockquote> </blockquote>
. .
Note that at least one space is needed between the list marker and
any following content, so these are not list items:
.
-one
2.two
.
<p>-one</p>
<p>2.two</p>
.
A list item may not contain blocks that are separated by more than A list item may not contain blocks that are separated by more than
one blank line. Thus, two blank lines will end a list, unless the one blank line. Thus, two blank lines will end a list, unless the
two blanks are contained in a [fenced code block]. two blanks are contained in a [fenced code block].
. .
- foo - foo
bar bar
- foo - foo
skipping to change at line 2924 skipping to change at line 2979
bar bar
. .
<ul> <ul>
<li> <li>
<p>foo</p> <p>foo</p>
<p>bar</p> <p>bar</p>
</li> </li>
</ul> </ul>
. .
3. **Empty list item.** A [list marker] followed by a 3. **Item starting with a blank line.** If a sequence of lines *Ls*
line containing only [whitespace] is a list item with no contents. starting with a single [blank line] constitute a (possibly empty)
sequence of blocks *Bs*, not separated from each other by more than
one blank line, and *M* is a list marker *M* of width *W*,
then the result of prepending *M* 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.
If a line is empty, then it need not be indented. The type of the
list item (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 number, based on the ordered list marker.
Here are some list items that start with a blank line but are not empty:
.
-
foo
-
```
bar
```
-
baz
.
<ul>
<li>foo</li>
<li>
<pre><code>bar
</code></pre>
</li>
<li>
<pre><code>baz
</code></pre>
</li>
</ul>
.
Here is an empty bullet list item: Here is an empty bullet list item:
. .
- foo - foo
- -
- bar - bar
. .
<ul> <ul>
<li>foo</li> <li>foo</li>
skipping to change at line 3480 skipping to change at line 3569
if its constituent list items begin with if its constituent list items begin with
[ordered list marker]s, and a [ordered list marker]s, and a
[bullet list](@bullet-list) if its constituent list [bullet list](@bullet-list) if its constituent list
items begin with [bullet list marker]s. items begin with [bullet list marker]s.
The [start number](@start-number) The [start number](@start-number)
of an [ordered list] is determined by the list number of of an [ordered list] is determined by the list number of
its initial list item. The numbers of subsequent list items are its initial list item. The numbers of subsequent list items are
disregarded. disregarded.
A list is [loose](@loose) if it any of its constituent A list is [loose](@loose) if any of its constituent
list items are separated by blank lines, or if 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 list items directly contain two block-level elements with a blank line
between them. Otherwise a list is [tight](@tight). between them. Otherwise a list is [tight](@tight).
(The difference in HTML output is that paragraphs in a loose list are (The difference in HTML output is that paragraphs in a loose list are
wrapped in `<p>` tags, while paragraphs in a tight list are not.) wrapped in `<p>` tags, while paragraphs in a tight list are not.)
Changing the bullet or ordered list delimiter starts a new list: Changing the bullet or ordered list delimiter starts a new list:
. .
- foo - foo
skipping to change at line 4462 skipping to change at line 4551
for efficient parsing strategies that do not backtrack. for efficient parsing strategies that do not backtrack.
First, some definitions. A [delimiter run](@delimiter-run) is either First, some definitions. A [delimiter run](@delimiter-run) is either
a sequence of one or more `*` characters that is not preceded or a sequence of one or more `*` characters that is not preceded or
followed by a `*` character, or a sequence of one or more `_` followed by a `*` character, or a sequence of one or more `_`
characters that is not preceded or followed by a `_` character. characters that is not preceded or followed by a `_` character.
A [left-flanking delimiter run](@left-flanking-delimiter-run) is A [left-flanking delimiter run](@left-flanking-delimiter-run) is
a [delimiter run] that is (a) not followed by [unicode whitespace], a [delimiter run] that is (a) not followed by [unicode whitespace],
and (b) either not followed by a [punctuation character], or and (b) either not followed by a [punctuation character], or
preceded by [unicode whitespace] or a [punctuation character]. preceded by [unicode whitespace] or a [punctuation character] or
the beginning of a line.
A [right-flanking delimiter run](@right-flanking-delimiter-run) is A [right-flanking delimiter run](@right-flanking-delimiter-run) is
a [delimiter run] that is (a) not preceded by [unicode whitespace], a [delimiter run] that is (a) not preceded by [unicode whitespace],
and (b) either not preceded by a [punctuation character], or and (b) either not preceded by a [punctuation character], or
followed by [unicode whitespace] or a [punctuation character]. followed by [unicode whitespace] or a [punctuation character] or
the end of a line.
Here are some examples of delimiter runs. Here are some examples of delimiter runs.
- left-flanking but not right-flanking: - left-flanking but not right-flanking:
``` ```
***abc ***abc
_abc _abc
**"abc" **"abc"
_"abc" _"abc"
skipping to change at line 4730 skipping to change at line 4821
This is not emphasis, because the closing `*` is preceded by This is not emphasis, because the closing `*` is preceded by
whitespace: whitespace:
. .
*foo bar * *foo bar *
. .
<p>*foo bar *</p> <p>*foo bar *</p>
. .
A newline also counts as whitespace:
.
*foo bar
*
.
<p>*foo bar</p>
<ul>
<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]:
. .
*(*foo) *(*foo)
. .
<p>*(*foo)</p> <p>*(*foo)</p>
. .
skipping to change at line 4857 skipping to change at line 4960
This is not strong emphasis, because the opening delimiter is This is not strong emphasis, because the opening delimiter is
followed by whitespace: followed by whitespace:
. .
__ foo bar__ __ foo bar__
. .
<p>__ foo bar__</p> <p>__ foo bar__</p>
. .
A newline counts as whitespace:
.
__
foo bar__
.
<p>__
foo bar__</p>
.
This is not strong emphasis, because the opening `__` is preceded This is not strong emphasis, because the opening `__` is preceded
by an alphanumeric and followed by punctuation: by an alphanumeric and followed by punctuation:
. .
a__"foo"__ a__"foo"__
. .
<p>a__&quot;foo&quot;__</p> <p>a__&quot;foo&quot;__</p>
. .
Intraword strong emphasis is forbidden with `__`: Intraword strong emphasis is forbidden with `__`:
skipping to change at line 5507 skipping to change at line 5619
<p><em>a <code>*</code></em></p> <p><em>a <code>*</code></em></p>
. .
. .
_a `_`_ _a `_`_
. .
<p><em>a <code>_</code></em></p> <p><em>a <code>_</code></em></p>
. .
. .
**a<http://foo.bar?q=**> **a<http://foo.bar/?q=**>
. .
<p>**a<a href="http://foo.bar?q=**">http://foo.bar?q=**</a></p> <p>**a<a href="http://foo.bar/?q=**">http://foo.bar/?q=**</a></p>
. .
. .
__a<http://foo.bar?q=__> __a<http://foo.bar/?q=__>
. .
<p>__a<a href="http://foo.bar?q=__">http://foo.bar?q=__</a></p> <p>__a<a href="http://foo.bar/?q=__">http://foo.bar/?q=__</a></p>
. .
## Links ## Links
A link contains [link text] (the visible text), a [link destination] A link contains [link text] (the visible text), a [link destination]
(the URI that is the link destination), and optionally a [link title]. (the URI that is the link destination), and optionally a [link title].
There are two basic kinds of links in Markdown. In [inline link]s the There are two basic kinds of links in Markdown. In [inline link]s the
destination and title are given immediately after the link text. In destination and title are given immediately after the link text. In
[reference link]s the destination and title are defined elsewhere in [reference link]s the destination and title are defined elsewhere in
the document. the document.
skipping to change at line 5571 skipping to change at line 5683
characters (`"`), including a `"` character only if it is characters (`"`), including a `"` character only if it is
backslash-escaped, or backslash-escaped, or
- a sequence of zero or more characters between straight single-quote - a sequence of zero or more characters between straight single-quote
characters (`'`), including a `'` character only if it is characters (`'`), including a `'` character only if it is
backslash-escaped, or backslash-escaped, or
- a sequence of zero or more characters between matching parentheses - a sequence of zero or more characters between matching parentheses
(`(...)`), including a `)` character only if it is backslash-escaped. (`(...)`), including a `)` character only if it is backslash-escaped.
Although [link title]s may span multiple lines, they may not contain
a [blank line].
An [inline link](@inline-link) consists of a [link text] followed immediately An [inline link](@inline-link) consists of a [link text] followed immediately
by a left parenthesis `(`, optional [whitespace], an optional by a left parenthesis `(`, optional [whitespace], an optional
[link destination], an optional [link title] separated from the link [link destination], an optional [link title] separated from the link
destination by [whitespace], optional [whitespace], and a right destination by [whitespace], optional [whitespace], and a right
parenthesis `)`. The link's text consists of the inlines contained parenthesis `)`. The link's text consists of the inlines contained
in the [link text] (excluding the enclosing square brackets). in the [link text] (excluding the enclosing square brackets).
The link's URI consists of the link destination, excluding enclosing The link's URI consists of the link destination, excluding enclosing
`<...>` if present, with backslash-escapes in effect as described `<...>` if present, with backslash-escapes in effect as described
above. The link's title consists of the link title, excluding its above. The link's title consists of the link title, excluding its
enclosing delimiters, with backslash-escapes in effect as described enclosing delimiters, with backslash-escapes in effect as described
skipping to change at line 5874 skipping to change at line 5989
<p>[foo <bar attr="](baz)"></p> <p>[foo <bar attr="](baz)"></p>
. .
. .
[foo`](/uri)` [foo`](/uri)`
. .
<p>[foo<code>](/uri)</code></p> <p>[foo<code>](/uri)</code></p>
. .
. .
[foo<http://example.com?search=](uri)> [foo<http://example.com/?search=](uri)>
. .
<p>[foo<a href="http://example.com?search=%5D(uri)">http://example.com?search=]( uri)</a></p> <p>[foo<a href="http://example.com/?search=%5D(uri)">http://example.com/?search= ](uri)</a></p>
. .
There are three kinds of [reference link](@reference-link)s: There are three kinds of [reference link](@reference-link)s:
[full](#full-reference-link), [collapsed](#collapsed-reference-link), [full](#full-reference-link), [collapsed](#collapsed-reference-link),
and [shortcut](#shortcut-reference-link). and [shortcut](#shortcut-reference-link).
A [full reference link](@full-reference-link) A [full reference link](@full-reference-link)
consists of a [link text], optional [whitespace], and a [link label] consists of a [link text], optional [whitespace], and a [link label]
that [matches] a [link reference definition] elsewhere in the document. that [matches] a [link reference definition] elsewhere in the document.
skipping to change at line 6014 skipping to change at line 6129
. .
[foo`][ref]` [foo`][ref]`
[ref]: /uri [ref]: /uri
. .
<p>[foo<code>][ref]</code></p> <p>[foo<code>][ref]</code></p>
. .
. .
[foo<http://example.com?search=][ref]> [foo<http://example.com/?search=][ref]>
[ref]: /uri [ref]: /uri
. .
<p>[foo<a href="http://example.com?search=%5D%5Bref%5D">http://example.com?searc h=][ref]</a></p> <p>[foo<a href="http://example.com/?search=%5D%5Bref%5D">http://example.com/?sea rch=][ref]</a></p>
. .
Matching is case-insensitive: Matching is case-insensitive:
. .
[foo][BaR] [foo][BaR]
[bar]: /url "title" [bar]: /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 6215 skipping to change at line 6330
. .
. .
[[*foo* bar]] [[*foo* bar]]
[*foo* bar]: /url "title" [*foo* bar]: /url "title"
. .
<p>[<a href="/url" title="title"><em>foo</em> bar</a>]</p> <p>[<a href="/url" title="title"><em>foo</em> bar</a>]</p>
. .
.
[[bar [foo]
[foo]: /url
.
<p>[[bar <a href="/url">foo</a></p>
.
The link labels are case-insensitive: The link labels are case-insensitive:
. .
[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 6559 skipping to change at line 6682
Here are some valid autolinks: Here are some valid autolinks:
. .
<http://foo.bar.baz> <http://foo.bar.baz>
. .
<p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p> <p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>
. .
. .
<http://foo.bar.baz?q=hello&id=22&boolean> <http://foo.bar.baz/test?q=hello&id=22&boolean>
. .
<p><a href="http://foo.bar.baz?q=hello&amp;id=22&amp;boolean">http://foo.bar.baz ?q=hello&amp;id=22&amp;boolean</a></p> <p><a href="http://foo.bar.baz/test?q=hello&amp;id=22&amp;boolean">http://foo.ba r.baz/test?q=hello&amp;id=22&amp;boolean</a></p>
. .
. .
<irc://foo.bar:2233/baz> <irc://foo.bar:2233/baz>
. .
<p><a href="irc://foo.bar:2233/baz">irc://foo.bar:2233/baz</a></p> <p><a href="irc://foo.bar:2233/baz">irc://foo.bar:2233/baz</a></p>
. .
Uppercase is also fine: Uppercase is also fine:
skipping to change at line 6586 skipping to change at line 6709
. .
Spaces are not allowed in autolinks: Spaces are not allowed in autolinks:
. .
<http://foo.bar/baz bim> <http://foo.bar/baz bim>
. .
<p>&lt;http://foo.bar/baz bim&gt;</p> <p>&lt;http://foo.bar/baz bim&gt;</p>
. .
Backslash-escapes do not work inside autolinks:
.
<http://example.com/\[\>
.
<p><a href="http://example.com/%5C%5B%5C">http://example.com/\[\</a></p>
.
An [email autolink](@email-autolink) An [email autolink](@email-autolink)
consists of `<`, followed by an [email address], consists of `<`, followed by an [email address],
followed by `>`. The link's label is the email address, followed by `>`. The link's label is the email address,
and the URL is `mailto:` followed by the email address. and the URL is `mailto:` followed by the email address.
An [email address](@email-address), An [email address](@email-address),
for these purposes, is anything that matches for these purposes, is anything that matches
the [non-normative regex from the HTML5 the [non-normative regex from the HTML5
spec](https://html.spec.whatwg.org/multipage/forms.html#e-mail-state-(type=email )): spec](https://html.spec.whatwg.org/multipage/forms.html#e-mail-state-(type=email )):
skipping to change at line 6613 skipping to change at line 6744
. .
<p><a href="mailto:foo@bar.example.com">foo@bar.example.com</a></p> <p><a href="mailto:foo@bar.example.com">foo@bar.example.com</a></p>
. .
. .
<foo+special@Bar.baz-bar0.com> <foo+special@Bar.baz-bar0.com>
. .
<p><a href="mailto:foo+special@Bar.baz-bar0.com">foo+special@Bar.baz-bar0.com</a ></p> <p><a href="mailto:foo+special@Bar.baz-bar0.com">foo+special@Bar.baz-bar0.com</a ></p>
. .
Backslash-escapes do not work inside email autolinks:
.
<foo\+@bar.example.com>
.
<p>&lt;foo+@bar.example.com&gt;</p>
.
These are not autolinks: These are not autolinks:
. .
<> <>
. .
<p>&lt;&gt;</p> <p>&lt;&gt;</p>
. .
. .
<heck://bing.bong> <heck://bing.bong>
 End of changes. 25 change blocks. 
19 lines changed or deleted 158 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/