---
title: CommonMark Spec
author: John MacFarlane
-version: 0.25
-date: '2016-03-24'
+version: 0.27
+date: '2016-11-18'
license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)'
...
## What is Markdown?
Markdown is a plain text format for writing structured documents,
-based on conventions used for indicating formatting in email and
-usenet posts. It was developed in 2004 by John Gruber, who wrote
-the first Markdown-to-HTML converter in perl, and it soon became
-widely used in websites. By 2014 there were dozens of
-implementations in many languages. Some of them extended basic
-Markdown syntax with conventions for footnotes, definition lists,
-tables, and other constructs, and some allowed output not just in
-HTML but in LaTeX and many other formats.
+based on conventions for indicating formatting in email
+and usenet posts. It was developed by John Gruber (with
+help from Aaron Swartz) and released in 2004 in the form of a
+[syntax description](http://daringfireball.net/projects/markdown/syntax)
+and a Perl script (`Markdown.pl`) for converting Markdown to
+HTML. In the next decade, dozens of implementations were
+developed in many languages. Some extended the original
+Markdown syntax with conventions for footnotes, tables, and
+other document elements. Some allowed Markdown documents to be
+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?
characters].
A [Unicode whitespace character](@) is
-any code point in the Unicode `Zs` class, or a tab (`U+0009`),
+any code point in the Unicode `Zs` general category, or a tab (`U+0009`),
carriage return (`U+000D`), newline (`U+000A`), or form feed
(`U+000C`).
A [punctuation character](@) is an [ASCII
punctuation character] or anything in
-the Unicode classes `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`.
+the general Unicode categories `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`.
## Tabs
Tabs in lines are not expanded to [spaces]. However,
-in contexts where indentation is significant for the
-document's structure, tabs behave as if they were replaced
-by spaces with a tab stop of 4 characters.
+in contexts where whitespace helps to define block structure,
+tabs behave as if they were replaced by spaces with a tab stop
+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
→foo→baz→→bim
</code></pre>
````````````````````````````````
-
```````````````````````````````` example
→foo→baz→→bim
.
</code></pre>
````````````````````````````````
-
```````````````````````````````` example
a→a
ὐ→a
</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
- foo
</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 three spaces.
+Since one of these 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
>→→foo
.
</ul>
````````````````````````````````
+```````````````````````````````` example
+#→Foo
+.
+<h1>Foo</h1>
+````````````````````````````````
+
+```````````````````````````````` example
+*→*→*→
+.
+<hr />
+````````````````````````````````
## Insecure characters
quotations, lists, headings, rules, and code blocks. Some blocks (like
block quotes and list items) contain other blocks; others (like
headings and paragraphs) contain [inline](@) content---text,
-links, emphasized text, images, code, and so on.
+links, emphasized text, images, code spans, and so on.
## Precedence
````````````````````````````````
-A tab will not work:
-
-```````````````````````````````` example
-#→foo
-.
-<p>#→foo</p>
-````````````````````````````````
-
-
This is not a heading, because the first `#` is escaped:
```````````````````````````````` example
meets a [start condition](@) (after up to three spaces
optional indentation). It ends with the first subsequent line that
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]
and the [end condition], the block will contain just that line.
`article`, `aside`, `base`, `basefont`, `blockquote`, `body`,
`caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,
`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`,
`meta`, `nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,
`section`, `source`, `summary`, `table`, `tbody`, `td`,
main :: IO ()
main = print $ parseTags tags
</code></pre>
+okay
.
<pre language="haskell"><code>
import Text.HTML.TagSoup
main :: IO ()
main = print $ parseTags tags
</code></pre>
+<p>okay</p>
````````````````````````````````
document.getElementById("demo").innerHTML = "Hello JavaScript!";
</script>
+okay
.
<script type="text/javascript">
// JavaScript example
document.getElementById("demo").innerHTML = "Hello JavaScript!";
</script>
+<p>okay</p>
````````````````````````````````
p {color:blue;}
</style>
+okay
.
<style
type="text/css">
p {color:blue;}
</style>
+<p>okay</p>
````````````````````````````````
bar
baz -->
+okay
.
<!-- Foo
bar
baz -->
+<p>okay</p>
````````````````````````````````
echo '>';
?>
+okay
.
<?php
echo '>';
?>
+<p>okay</p>
````````````````````````````````
}
}
]]>
+okay
.
<![CDATA[
function matchwo(a,b)
}
}
]]>
+<p>okay</p>
````````````````````````````````
````````````````````````````````
-The Laziness clause allows us to omit the `>` before a
-paragraph continuation line:
+The Laziness clause allows us to omit the `>` before
+[paragraph continuation text]:
```````````````````````````````` example
> # Foo
````````````````````````````````
-Note that in the following case, we have a paragraph
-continuation line:
+Note that in the following case, we have a [lazy
+continuation line]:
```````````````````````````````` example
> foo
the `- bar` is indented too far to start a list, and can't
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:
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 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
*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
If the list item is ordered, then it is also assigned a start
number, based on the ordered list marker.
+ Exceptions: When the first list item in a [list] 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
```````````````````````````````` example
````````````````````````````````
-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
-two blanks are contained in a [fenced code block].
+A list item may contain blocks that are separated by more than
+one blank line.
```````````````````````````````` example
- foo
- bar
-
-- foo
-
-
- bar
-
-- ```
- foo
-
bar
- ```
-
-- baz
-
- + ```
- foo
-
-
- bar
- ```
.
<ul>
<li>
<p>foo</p>
<p>bar</p>
</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>
````````````````````````````````
A list item that contains an indented code block will preserve
-empty lines within the code block verbatim, unless there are two
-or more empty lines in a row (since as described above, two
-blank lines end the list):
+empty lines within the code block verbatim.
```````````````````````````````` example
- Foo
bar
+
baz
.
<ul>
<p>Foo</p>
<pre><code>bar
-baz
-</code></pre>
-</li>
-</ul>
-````````````````````````````````
-
-
-```````````````````````````````` example
-- Foo
-
- bar
-
- baz
-.
-<ul>
-<li>
-<p>Foo</p>
-<pre><code>bar
+baz
</code></pre>
</li>
</ul>
-<pre><code> baz
-</code></pre>
````````````````````````````````
-
Note that ordered list start numbers must be nine digits or less:
```````````````````````````````` example
</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
- foo
- bar
- baz
+ - boo
.
<ul>
<li>foo
<ul>
<li>bar
<ul>
-<li>baz</li>
+<li>baz
+<ul>
+<li>boo</li>
+</ul>
+</li>
</ul>
</li>
</ul>
- foo
- bar
- baz
+ - boo
.
<ul>
<li>foo</li>
<li>bar</li>
<li>baz</li>
+<li>boo</li>
</ul>
````````````````````````````````
A [list](@) is a sequence of one or more
list items [of the same type]. The list items
-may be separated by single [blank lines], but two
-blank lines end all containing lists.
+may be separated by any number of blank lines.
Two list items are [of the same type](@)
if they begin with a [list marker] of the same type.
</ul>
````````````````````````````````
-
`Markdown.pl` does not allow this, through fear of triggering a list
via a numeral in a hard-wrapped line:
-```````````````````````````````` example
+``` markdown
The number of windows in my house is
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, `Markdown.pl` *does* allow a blockquote to interrupt a paragraph,
-even though the same considerations might apply. We think that the two
-cases should be treated the same. Here are two reasons for allowing
-lists to interrupt paragraphs:
+Oddly, though, `Markdown.pl` *does* allow a blockquote to
+interrupt a paragraph, even though the same considerations might
+apply.
-First, it is natural and not uncommon for people to start lists without
-blank lines:
+In CommonMark, we do allow lists to interrupt paragraphs, for
+two reasons. First, it is natural and not uncommon for people
+to start lists without blank lines:
- I need to buy
- - new shoes
- - a coat
- - a plane ticket
+``` markdown
+I need to buy
+- new shoes
+- a coat
+- a plane ticket
+```
Second, we are attracted to a
(Indeed, the spec for [list items] and [block quotes] presupposes
this principle.) This principle implies that if
- * I need to buy
- - new shoes
- - a coat
- - a plane ticket
+``` markdown
+ * I need to buy
+ - new shoes
+ - a coat
+ - a plane ticket
+```
is a list item containing a paragraph followed by a nested sublist,
as all Markdown implementations agree it is (though the paragraph
may be rendered without `<p>` tags, since the list is "tight"),
then
- I need to buy
- - new shoes
- - a coat
- - a plane ticket
+``` markdown
+I need to buy
+- new shoes
+- a coat
+- a plane ticket
+```
by itself should be a paragraph followed by a nested sublist.
-Our adherence to the [principle of uniformity]
-thus inclines us to think that there are two coherent packages:
+Since it is well established Markdown practice to allow lists to
+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,
- including lists that occur as sublists inside other list items.
+In order to solve of unwanted lists in paragraphs with
+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>
+````````````````````````````````
+
+We may still get an unintended result in cases like
+
+```````````````````````````````` example
+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>
+````````````````````````````````
-[reStructuredText](http://docutils.sourceforge.net/rst.html) takes
-the first approach, for which there is much to be said. But the second
-seems more consistent with established practice with Markdown.
+but this rule should prevent most spurious list captures.
-There can be blank lines between items, but two blank lines end
-a list:
+There can be any number of blank lines between items:
```````````````````````````````` example
- foo
<li>
<p>bar</p>
</li>
-</ul>
-<ul>
-<li>baz</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>
+<li>
+<p>baz</p>
+</li>
</ul>
````````````````````````````````
-
-Indeed, two blank lines will end *all* containing lists:
-
```````````````````````````````` example
- foo
- bar
<ul>
<li>bar
<ul>
-<li>baz</li>
+<li>
+<p>baz</p>
+<p>bim</p>
+</li>
</ul>
</li>
</ul>
</li>
</ul>
-<pre><code> bim
-</code></pre>
````````````````````````````````
-Thus, two blank lines can be used to separate consecutive lists of
-the same type, or to separate a list from an indented code block
-that would otherwise be parsed as a subparagraph of the final list
-item:
+To separate consecutive lists of the same type, or to separate a
+list from an indented code block that would otherwise be parsed
+as a subparagraph of the final list item, you can insert a blank HTML
+comment:
```````````````````````````````` example
- foo
- bar
+<!-- -->
- baz
- bim
<li>foo</li>
<li>bar</li>
</ul>
+<!-- -->
<ul>
<li>baz</li>
<li>bim</li>
- foo
+<!-- -->
code
.
<p>foo</p>
</li>
</ul>
+<!-- -->
<pre><code>code
</code></pre>
````````````````````````````````
````````````````````````````````
+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
anyway? A: Because we might be targeting a non-HTML format, and we
shouldn't rely on HTML-specific rendering assumptions.
<p>`foo</p>
````````````````````````````````
+The following case also illustrates the need for opening and
+closing backtick strings to be equal in length:
+
+```````````````````````````````` example
+`foo``bar``
+.
+<p>`foo<code>bar</code></p>
+````````````````````````````````
+
## Emphasis and strong emphasis
A [left-flanking delimiter run](@) is
a [delimiter run] that is (a) not followed by [Unicode whitespace],
-and (b) either not followed by a [punctuation character], or
+and (b) not followed by a [punctuation character], or
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) either not preceded by a [punctuation character], or
+and (b) not preceded by a [punctuation character], or
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.
7. A double `**` [can close strong emphasis](@)
iff it is part of a [right-flanking delimiter run].
-8. A double `__` [can close strong emphasis]
+8. A double `__` [can close strong emphasis] iff
it is part of a [right-flanking delimiter run]
and either (a) not part of a [left-flanking delimiter run]
or (b) part of a [left-flanking delimiter run]
9. Emphasis begins with a delimiter that [can open emphasis] and ends
with a delimiter that [can close emphasis], and that uses the same
- character (`_` or `*`) as the opening delimiter. There must
- be a nonempty sequence of inlines between the open delimiter
- and the closing delimiter; these form the contents of the emphasis
- inline.
+ character (`_` or `*`) as the opening delimiter. The
+ opening and closing delimiters must belong to separate
+ [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.
10. Strong emphasis begins with a delimiter that
[can open strong emphasis] and ends with a delimiter that
[can close strong emphasis], and that uses the same character
- (`_` or `*`) as the opening delimiter.
- There must be a nonempty sequence of inlines between the open
- delimiter and the closing delimiter; these form the contents of
- the strong emphasis inline.
+ (`_` or `*`) as the opening delimiter. The
+ opening and closing delimiters must belong to separate
+ [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.
11. A literal `*` character cannot occur at the beginning or end of
`*`-delimited emphasis or `**`-delimited strong emphasis, unless it
an interpretation `<strong>...</strong>` is always preferred to
`<em><em>...</em></em>`.
-14. An interpretation `<strong><em>...</em></strong>` is always
- preferred to `<em><strong>..</strong></em>`.
+14. An interpretation `<em><strong>...</strong></em>` is always
+ preferred to `<strong><em>...</em></strong>`.
15. When two potential emphasis or strong emphasis spans overlap,
so that the second begins before the first ends and ends after
the first ends, the first takes precedence. Thus, for example,
`*foo _bar* baz_` is parsed as `<em>foo _bar</em> baz_` rather
- than `*foo <em>bar* baz</em>`. For the same reason,
- `**foo*bar**` is parsed as `<em><em>foo</em>bar</em>*`
- rather than `<strong>foo*bar</strong>`.
+ than `*foo <em>bar* baz</em>`.
16. When there are two potential emphasis or strong emphasis spans
with the same closing delimiter, the shorter one (the one that
*foo bar
*
.
-<p>*foo bar</p>
-<ul>
-<li></li>
-</ul>
+<p>*foo bar
+*</p>
````````````````````````````````
<p><em>foo <strong>bar</strong> baz</em></p>
````````````````````````````````
-
-But note:
-
```````````````````````````````` example
*foo**bar**baz*
.
-<p><em>foo</em><em>bar</em><em>baz</em></p>
+<p><em>foo<strong>bar</strong>baz</em></p>
````````````````````````````````
+Note that in the preceding case, the interpretation
+
+``` 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:
-The difference is that in the preceding case, the internal delimiters
-[can close emphasis], while in the cases with spaces, they cannot.
```````````````````````````````` example
***foo** bar*
````````````````````````````````
-Note, however, that in the following case we get no strong
-emphasis, because the opening delimiter is closed by the first
-`*` before `bar`:
-
```````````````````````````````` example
*foo**bar***
.
-<p><em>foo</em><em>bar</em>**</p>
+<p><em>foo<strong>bar</strong></em></p>
````````````````````````````````
-
Indefinite levels of nesting are possible:
```````````````````````````````` example
````````````````````````````````
-But note:
-
```````````````````````````````` example
**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
***foo* bar**
.
```````````````````````````````` example
***foo***
.
-<p><strong><em>foo</em></strong></p>
+<p><em><strong>foo</strong></em></p>
````````````````````````````````
```````````````````````````````` example
_____foo_____
.
-<p><strong><strong><em>foo</em></strong></strong></p>
+<p><em><strong><strong>foo</strong></strong></em></p>
````````````````````````````````
````````````````````````````````
-```````````````````````````````` example
-**foo*bar**
-.
-<p><em><em>foo</em>bar</em>*</p>
-````````````````````````````````
-
-
```````````````````````````````` example
*foo __bar *baz bim__ bam*
.
- 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 that is not itself
- inside a balanced pair of unescaped parentheses.
+ a balanced pair of unescaped parentheses.
A [link title](@) consists of either
<p><a href="(foo)">link</a></p>
````````````````````````````````
-One level of balanced parentheses is allowed without escaping:
-
-```````````````````````````````` example
-[link]((foo)and(bar))
-.
-<p><a href="(foo)and(bar)">link</a></p>
-````````````````````````````````
-
-However, if you have parentheses within parentheses, you need to escape
-or use the `<...>` form:
+Any number parentheses are allowed without escaping, as long as they are
+balanced:
```````````````````````````````` example
[link](foo(and(bar)))
.
-<p>[link](foo(and(bar)))</p>
+<p><a href="foo(and(bar))">link</a></p>
````````````````````````````````
+However, if you have unbalanced parentheses, you need to escape or use the
+`<...>` form:
```````````````````````````````` example
-[link](foo(and\(bar\)))
+[link](foo\(and\(bar\))
.
-<p><a href="foo(and(bar))">link</a></p>
+<p><a href="foo(and(bar)">link</a></p>
````````````````````````````````
```````````````````````````````` example
-[link](<foo(and(bar))>)
+[link](<foo(and(bar)>)
.
-<p><a href="foo(and(bar))">link</a></p>
+<p><a href="foo(and(bar)">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:
```````````````````````````````` example
[link reference definition] elsewhere in the
document and is not followed by `[]` or a link label.
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.
Thus, `[foo]` is equivalent to `[foo][]`.
````````````````````````````````
-Full references take precedence over shortcut references:
+Full and compact references take precedence over shortcut
+references:
```````````````````````````````` example
[foo][bar]
<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,
`[foo]` as normal text:
````````````````````````````````
-If you just want bracketed text, you can backslash-escape the
-opening `!` and `[`:
+If you just want a literal `!` followed by bracketed text, you can
+backslash-escape the opening `[`:
```````````````````````````````` example
-\!\[foo]
+!\[foo]
[foo]: /url "title"
.
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
-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
browsers. In the examples here, a [line ending] will be used.)
[lazy continuation line].
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
in step 1 before creating the new block as a child of the last
matched block.
Code Review / simantics / platform.git / blobdiff