Couldn't find wdiff. Falling back to builtin diff colouring... Diff: spec.txt - spec.txt
 spec.txt   spec.txt 
--- ---
title: CommonMark Spec title: CommonMark Spec
author: John MacFarlane author: John MacFarlane
version: '0.30' version: '0.31.2'
date: '2021-06-19' date: '2024-01-28'
license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)' license: '[CC-BY-SA 4.0](https://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 for indicating formatting in email based on conventions for indicating formatting in email
and usenet posts. It was developed by John Gruber (with and usenet posts. It was developed by John Gruber (with
help from Aaron Swartz) and released in 2004 in the form of a help from Aaron Swartz) and released in 2004 in the form of a
[syntax description](http://daringfireball.net/projects/markdown/syntax) [syntax description](https://daringfireball.net/projects/markdown/syntax)
and a Perl script (`Markdown.pl`) for converting Markdown to and a Perl script (`Markdown.pl`) for converting Markdown to
HTML. In the next decade, dozens of implementations were HTML. In the next decade, dozens of implementations were
developed in many languages. Some extended the original developed in many languages. Some extended the original
Markdown syntax with conventions for footnotes, tables, and Markdown syntax with conventions for footnotes, tables, and
other document elements. Some allowed Markdown documents to be other document elements. Some allowed Markdown documents to be
rendered in formats other than HTML. Websites like Reddit, rendered in formats other than HTML. Websites like Reddit,
StackOverflow, and GitHub had millions of people using Markdown. StackOverflow, and GitHub had millions of people using Markdown.
And Markdown started to be used beyond the web, to author books, And Markdown started to be used beyond the web, to author books,
articles, slide shows, letters, and lecture notes. articles, slide shows, letters, and lecture notes.
What distinguishes Markdown from many other lightweight markup What distinguishes Markdown from many other lightweight markup
syntaxes, which are often easier to write, is its readability. syntaxes, which are often easier to write, is its readability.
As Gruber writes: As Gruber writes:
> The overriding design goal for Markdown's formatting syntax is > The overriding design goal for Markdown's formatting syntax is
> to make it as readable as possible. The idea is that a > to make it as readable as possible. The idea is that a
> Markdown-formatted document should be publishable as-is, as > Markdown-formatted document should be publishable as-is, as
> plain text, without looking like it's been marked up with tags > plain text, without looking like it's been marked up with tags
> or formatting instructions. > or formatting instructions.
> (<http://daringfireball.net/projects/markdown/>) > (<https://daringfireball.net/projects/markdown/>)
The point can be illustrated by comparing a sample of The point can be illustrated by comparing a sample of
[AsciiDoc](http://www.methods.co.nz/asciidoc/) with [AsciiDoc](https://asciidoc.org/) with
an equivalent sample of Markdown. Here is a sample of an equivalent sample of Markdown. Here is a sample of
AsciiDoc from the AsciiDoc manual: AsciiDoc from the AsciiDoc manual:
``` ```
1. List item one. 1. List item one.
+ +
List item one continued with a second paragraph followed by an List item one continued with a second paragraph followed by an
Indented block. Indented block.
+ +
................. .................
skipping to change at line 106 skipping to change at line 106
``` ```
The AsciiDoc version is, arguably, easier to write. You don't need The AsciiDoc version is, arguably, easier to write. You don't need
to worry about indentation. But the Markdown version is much easier 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 to read. The nesting of list items is apparent to the eye in the
source, not just in the processed document. 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](https://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
not fully explicit about sublists. It is natural to think that not fully explicit about sublists. It is natural to think that
they, too, must be indented four spaces, but `Markdown.pl` does they, too, must be indented four spaces, but `Markdown.pl` does
not require that. This is hardly a "corner case," and divergences not require that. This is hardly a "corner case," and divergences
between implementations on this issue often lead to surprises for between implementations on this issue often lead to surprises for
users in real documents. (See [this comment by John users in real documents. (See [this comment by John
Gruber](http://article.gmane.org/gmane.text.markdown.general/1997).) Gruber](https://web.archive.org/web/20170611172104/http://article.gmane.org/ gmane.text.markdown.general/1997).)
2. Is a blank line needed before a block quote or heading? 2. Is a blank line needed before a block quote or heading?
Most implementations do not require the blank line. However, Most implementations do not require the blank line. However,
this can lead to unexpected results in hard-wrapped text, and this can lead to unexpected results in hard-wrapped text, and
also to ambiguities in parsing (note that some implementations also to ambiguities in parsing (note that some implementations
put the heading inside the blockquote, while others do not). put the heading inside the blockquote, while others do not).
(John Gruber has also spoken [in favor of requiring the blank (John Gruber has also spoken [in favor of requiring the blank
lines](http://article.gmane.org/gmane.text.markdown.general/2146).) lines](https://web.archive.org/web/20170611172104/http://article.gmane.org/g mane.text.markdown.general/2146).)
3. Is a blank line needed before an indented code block? 3. Is a blank line needed before an indented code block?
(`Markdown.pl` requires it, but this is not mentioned in the (`Markdown.pl` requires it, but this is not mentioned in the
documentation, and some implementations do not require it.) documentation, and some implementations do not require it.)
``` markdown ``` markdown
paragraph paragraph
code? code?
``` ```
skipping to change at line 158 skipping to change at line 158
``` markdown ``` markdown
1. one 1. one
- a - a
- b - b
2. two 2. two
``` ```
(There are some relevant comments by John Gruber (There are some relevant comments by John Gruber
[here](http://article.gmane.org/gmane.text.markdown.general/2554).) [here](https://web.archive.org/web/20170611172104/http://article.gmane.org/g mane.text.markdown.general/2554).)
5. Can list markers be indented? Can ordered list markers be right-aligned? 5. Can list markers be indented? Can ordered list markers be right-aligned?
``` markdown ``` markdown
8. item 1 8. item 1
9. item 2 9. item 2
10. item 2a 10. item 2a
``` ```
6. Is this one list with a thematic break in its second item, 6. Is this one list with a thematic break in its second item,
skipping to change at line 319 skipping to change at line 319
A [line ending](@) is a line feed (`U+000A`), a carriage return A [line ending](@) is a line feed (`U+000A`), a carriage return
(`U+000D`) not followed by a line feed, or a carriage return and a (`U+000D`) not followed by a line feed, or a carriage return and a
following line feed. following line feed.
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](@). (`U+0020`) or tabs (`U+0009`), is called a [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 [Unicode whitespace character](@) is A [Unicode whitespace character](@) is a character in the Unicode `Zs` general
any code point in the Unicode `Zs` general category, or a tab (`U+0009`), category, or a tab (`U+0009`), line feed (`U+000A`), form feed (`U+000C`), or
line feed (`U+000A`), form feed (`U+000C`), or carriage return (`U+000D`). carriage return (`U+000D`).
[Unicode whitespace](@) is a sequence of one or more [Unicode whitespace](@) is a sequence of one or more
[Unicode whitespace characters]. [Unicode whitespace characters].
A [tab](@) is `U+0009`. A [tab](@) is `U+0009`.
A [space](@) is `U+0020`. A [space](@) is `U+0020`.
An [ASCII control character](@) is a character between `U+0000–1F` (both An [ASCII control character](@) is a character between `U+0000–1F` (both
including) or `U+007F`. including) or `U+007F`.
An [ASCII punctuation character](@) An [ASCII punctuation character](@)
is `!`, `"`, `#`, `$`, `%`, `&`, `'`, `(`, `)`, is `!`, `"`, `#`, `$`, `%`, `&`, `'`, `(`, `)`,
`*`, `+`, `,`, `-`, `.`, `/` (U+0021–2F), `*`, `+`, `,`, `-`, `.`, `/` (U+0021–2F),
`:`, `;`, `<`, `=`, `>`, `?`, `@` (U+003A–0040), `:`, `;`, `<`, `=`, `>`, `?`, `@` (U+003A–0040),
`[`, `\`, `]`, `^`, `_`, `` ` `` (U+005B–0060), `[`, `\`, `]`, `^`, `_`, `` ` `` (U+005B–0060),
`{`, `|`, `}`, or `~` (U+007B–007E). `{`, `|`, `}`, or `~` (U+007B–007E).
A [Unicode punctuation character](@) is an [ASCII A [Unicode punctuation character](@) is a character in the Unicode `P`
punctuation character] or anything in (puncuation) or `S` (symbol) general categories.
the general Unicode categories `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 spaces help to define block structure, in contexts where spaces help to define block structure,
tabs behave as if they were replaced by spaces with a tab stop tabs behave as if they were replaced by spaces with a tab stop
of 4 characters. of 4 characters.
Thus, for example, a tab can be used instead of four spaces Thus, for example, a tab can be used instead of four spaces
in an indented code block. (Note, however, that internal in an indented code block. (Note, however, that internal
skipping to change at line 571 skipping to change at line 570
```````````````````````````````` example ```````````````````````````````` example
~~~ ~~~
\[\] \[\]
~~~ ~~~
. .
<pre><code>\[\] <pre><code>\[\]
</code></pre> </code></pre>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<http://example.com?find=\*> <https://example.com?find=\*>
. .
<p><a href="http://example.com?find=%5C*">http://example.com?find=\*</a></p> <p><a href="https://example.com?find=%5C*">https://example.com?find=\*</a></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<a href="/bar\/)"> <a href="/bar\/)">
. .
<a href="/bar\/)"> <a href="/bar\/)">
```````````````````````````````` ````````````````````````````````
But they work in all other contexts, including URLs and link titles, But they work in all other contexts, including URLs and link titles,
link references, and [info strings] in [fenced code blocks]: link references, and [info strings] in [fenced code blocks]:
skipping to change at line 1264 skipping to change at line 1263
have more than 3 spaces of indentation, followed by have more than 3 spaces of indentation, followed by
a [setext heading underline]. The lines of text must be such a [setext heading underline]. The lines of text must be such
that, were they not followed by the setext heading underline, that, were they not followed by the setext heading underline,
they would be interpreted as a paragraph: they cannot be they would be interpreted as a paragraph: they cannot be
interpretable as a [code fence], [ATX heading][ATX headings], interpretable as a [code fence], [ATX heading][ATX headings],
[block quote][block quotes], [thematic break][thematic breaks], [block quote][block quotes], [thematic break][thematic breaks],
[list item][list items], or [HTML block][HTML blocks]. [list item][list items], or [HTML block][HTML blocks].
A [setext heading underline](@) is a sequence of A [setext heading underline](@) is a sequence of
`=` characters or a sequence of `-` characters, with no more than 3 `=` characters or a sequence of `-` characters, with no more than 3
spaces of indentation and any number of trailing spaces or tabs. If a line spaces of indentation and any number of trailing spaces or tabs.
containing a single `-` can be interpreted as an
empty [list items], it should be interpreted this way
and not as a [setext heading underline].
The heading is a level 1 heading if `=` characters are used in The heading is a level 1 heading if `=` characters are used in
the [setext heading underline], and a level 2 heading if `-` the [setext heading underline], and a level 2 heading if `-`
characters are used. The contents of the heading are the result characters are used. The contents of the heading are the result
of parsing the preceding lines of text as CommonMark inline of parsing the preceding lines of text as CommonMark inline
content. content.
In general, a setext heading need not be preceded or followed by a In general, a setext heading need not be preceded or followed by a
blank line. However, it cannot interrupt a paragraph, so when a blank line. However, it cannot interrupt a paragraph, so when a
setext heading comes after a paragraph, a blank line is needed between setext heading comes after a paragraph, a blank line is needed between
skipping to change at line 1855 skipping to change at line 1851
indented, it is preserved unchanged. If it is indented N spaces or less, all indented, it is preserved unchanged. If it is indented N spaces or less, all
of the indentation is removed.) of the indentation is removed.)
The closing code fence may be preceded by up to three spaces of indentation, and The closing code fence may be preceded by up to three spaces of indentation, and
may be followed only by spaces or tabs, which are ignored. If the end of the may be followed only by spaces or tabs, which are ignored. If the end of the
containing block (or document) is reached and no closing code fence containing block (or document) is reached and no closing code fence
has been found, the code block contains all of the lines after the has been found, the code block contains all of the lines after the
opening code fence until the end of the containing block (or opening code fence until the end of the containing block (or
document). (An alternative spec would require backtracking in the document). (An alternative spec would require backtracking in the
event that a closing code fence is not found. But this makes parsing event that a closing code fence is not found. But this makes parsing
much less efficient, and there seems to be no real down side to the much less efficient, and there seems to be no real downside to the
behavior described here.) behavior described here.)
A fenced code block may interrupt a paragraph, and does not require A fenced code block may interrupt a paragraph, and does not require
a blank line either before or after. a blank line either before or after.
The content of a code fence is treated as literal text, not parsed The content of a code fence is treated as literal text, not parsed
as inlines. The first word of the [info string] is typically used to as inlines. The first word of the [info string] is typically used to
specify the language of the code sample, and rendered in the `class` specify the language of the code sample, and rendered in the `class`
attribute of the `code` tag. However, this spec does not mandate any attribute of the `code` tag. However, this spec does not mandate any
particular treatment of the [info string]. particular treatment of the [info string].
skipping to change at line 2255 skipping to change at line 2251
**End condition:** line contains the string `?>`. **End condition:** line contains the string `?>`.
4. **Start condition:** line begins with the string `<!` 4. **Start condition:** line begins with the string `<!`
followed by an ASCII letter.\ followed by an ASCII letter.\
**End condition:** line contains the character `>`. **End condition:** line contains the character `>`.
5. **Start condition:** line begins with the string 5. **Start condition:** line begins with the string
`<![CDATA[`.\ `<![CDATA[`.\
**End condition:** line contains the string `]]>`. **End condition:** line contains the string `]]>`.
6. **Start condition:** line begins the string `<` or `</` 6. **Start condition:** line begins with the string `<` or `</`
followed by one of the strings (case-insensitive) `address`, followed by one of the strings (case-insensitive) `address`,
`article`, `aside`, `base`, `basefont`, `blockquote`, `body`, `article`, `aside`, `base`, `basefont`, `blockquote`, `body`,
`caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`, `caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,
`dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`, `dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`,
`footer`, `form`, `frame`, `frameset`, `footer`, `form`, `frame`, `frameset`,
`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`,
`html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`, `html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`,
`nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`, `nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,
`section`, `source`, `summary`, `table`, `tbody`, `td`, `search`, `section`, `summary`, `table`, `tbody`, `td`,
`tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed `tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed
by a space, a tab, the end of the line, the string `>`, or by a space, a tab, the end of the line, the string `>`, or
the string `/>`.\ the string `/>`.\
**End condition:** line is followed by a [blank line]. **End condition:** line is followed by a [blank line].
7. **Start condition:** line begins with a complete [open tag] 7. **Start condition:** line begins with a complete [open tag]
(with any [tag name] other than `pre`, `script`, (with any [tag name] other than `pre`, `script`,
`style`, or `textarea`) or a complete [closing tag], `style`, or `textarea`) or a complete [closing tag],
followed by zero or more spaces and tabs, followed by the end of the line.\ followed by zero or more spaces and tabs, followed by the end of the line.\
**End condition:** line is followed by a [blank line]. **End condition:** line is followed by a [blank line].
skipping to change at line 3869 skipping to change at line 3865
`.` 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 character other than a space or tab, and *M* is blocks *Bs* starting with a character other than a space or tab, and *M* is
a list marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces of indentation, a list marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces of indentation,
then the result of prepending *M* and the following spaces to the first line 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 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 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: Exceptions:
1. When the first list item in a [list] interrupts 1. When the first list item in a [list] interrupts
a paragraph---that is, when it starts on a line that would a paragraph---that is, when it starts on a line that would
otherwise count as [paragraph continuation text]---then (a) otherwise count as [paragraph continuation text]---then (a)
skipping to change at line 4259 skipping to change at line 4255
</code></pre> </code></pre>
<p>paragraph</p> <p>paragraph</p>
<pre><code>more code <pre><code>more code
</code></pre> </code></pre>
</li> </li>
</ol> </ol>
```````````````````````````````` ````````````````````````````````
Note that rules #1 and #2 only apply to two cases: (a) cases Note that rules #1 and #2 only apply to two cases: (a) cases
in which the lines to be included in a list item begin with a in which the lines to be included in a list item begin with a
characer other than a space or tab, and (b) cases in which character other than a space or tab, and (b) cases in which
they begin with an indented code they begin with an indented code
block. In a case like the following, where the first block begins with block. In a case like the following, where the first block begins with
three spaces of indentation, the rules do not allow us to form a list item by three spaces of indentation, the rules do not allow us to form a list item by
indenting the whole thing and prepending a list marker: indenting the whole thing and prepending a list marker:
```````````````````````````````` example ```````````````````````````````` example
foo foo
bar bar
. .
skipping to change at line 5051 skipping to change at line 5047
- 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.
Since it is well established Markdown practice to allow lists to Since it is well established Markdown practice to allow lists to
interrupt paragraphs inside list items, the [principle of interrupt paragraphs inside list items, the [principle of
uniformity] requires us to allow this outside list items as uniformity] requires us to allow this outside list items as
well. ([reStructuredText](http://docutils.sourceforge.net/rst.html) well. ([reStructuredText](https://docutils.sourceforge.net/rst.html)
takes a different approach, requiring blank lines before lists takes a different approach, requiring blank lines before lists
even inside other list items.) even inside other list items.)
In order to solve of unwanted lists in paragraphs with In order to solve the problem of unwanted lists in paragraphs with
hard-wrapped numerals, we allow only lists starting with `1` to hard-wrapped numerals, we allow only lists starting with `1` to
interrupt paragraphs. Thus, interrupt paragraphs. Thus,
```````````````````````````````` example ```````````````````````````````` example
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>The number of windows in my house is
14. The number of doors is 6.</p> 14. The number of doors is 6.</p>
```````````````````````````````` ````````````````````````````````
skipping to change at line 5721 skipping to change at line 5717
```````````````````````````````` example ```````````````````````````````` example
<a href="`">` <a href="`">`
. .
<p><a href="`">`</p> <p><a href="`">`</p>
```````````````````````````````` ````````````````````````````````
And this is code: And this is code:
```````````````````````````````` example ```````````````````````````````` example
`<http://foo.bar.`baz>` `<https://foo.bar.`baz>`
. .
<p><code>&lt;http://foo.bar.</code>baz&gt;`</p> <p><code>&lt;https://foo.bar.</code>baz&gt;`</p>
```````````````````````````````` ````````````````````````````````
But this is an autolink: But this is an autolink:
```````````````````````````````` example ```````````````````````````````` example
<http://foo.bar.`baz>` <https://foo.bar.`baz>`
. .
<p><a href="http://foo.bar.%60baz">http://foo.bar.`baz</a>`</p> <p><a href="https://foo.bar.%60baz">https://foo.bar.`baz</a>`</p>
```````````````````````````````` ````````````````````````````````
When a backtick string is not closed by a matching backtick string, When a backtick string is not closed by a matching backtick string,
we just have literal backticks: we just have literal backticks:
```````````````````````````````` example ```````````````````````````````` example
```foo`` ```foo``
. .
<p>```foo``</p> <p>```foo``</p>
```````````````````````````````` ````````````````````````````````
skipping to change at line 5761 skipping to change at line 5757
```````````````````````````````` example ```````````````````````````````` example
`foo``bar`` `foo``bar``
. .
<p>`foo<code>bar</code></p> <p>`foo<code>bar</code></p>
```````````````````````````````` ````````````````````````````````
## Emphasis and strong emphasis ## Emphasis and strong emphasis
John Gruber's original [Markdown syntax John Gruber's original [Markdown syntax
description](http://daringfireball.net/projects/markdown/syntax#em) says: description](https://daringfireball.net/projects/markdown/syntax#em) says:
> Markdown treats asterisks (`*`) and underscores (`_`) as indicators of > Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
> emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML > emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML
> `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML `<strong>` > `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML `<strong>`
> tag. > tag.
This is enough for most users, but these rules leave much undecided, This is enough for most users, but these rules leave much undecided,
especially when it comes to nested emphasis. The original especially when it comes to nested emphasis. The original
`Markdown.pl` test suite makes it clear that triple `***` and `Markdown.pl` test suite makes it clear that triple `***` and
`___` delimiters can be used for strong emphasis, and most `___` delimiters can be used for strong emphasis, and most
skipping to change at line 5863 skipping to change at line 5859
- Neither left nor right-flanking: - Neither left nor right-flanking:
``` ```
abc *** def abc *** def
a _ b a _ b
``` ```
(The idea of distinguishing left-flanking and right-flanking (The idea of distinguishing left-flanking and right-flanking
delimiter runs based on the character before and the character delimiter runs based on the character before and the character
after comes from Roopesh Chander's after comes from Roopesh Chander's
[vfmd](http://www.vfmd.org/vfmd-spec/specification/#procedure-for-identifying-em phasis-tags). [vfmd](https://web.archive.org/web/20220608143320/http://www.vfmd.org/vfmd-spec/ specification/#procedure-for-identifying-emphasis-tags).
vfmd uses the terminology "emphasis indicator string" instead of "delimiter vfmd uses the terminology "emphasis indicator string" instead of "delimiter
run," and its rules for distinguishing left- and right-flanking runs run," and its rules for distinguishing left- and right-flanking runs
are a bit more complex than the ones given here.) are a bit more complex than the ones given here.)
The following rules define emphasis and strong emphasis: The following rules define emphasis and strong emphasis:
1. A single `*` character [can open emphasis](@) 1. A single `*` character [can open emphasis](@)
iff (if and only if) it is part of a [left-flanking delimiter run]. iff (if and only if) it is part of a [left-flanking delimiter run].
2. A single `_` character [can open emphasis] iff 2. A single `_` character [can open emphasis] iff
skipping to change at line 6001 skipping to change at line 5997
```````````````````````````````` ````````````````````````````````
Unicode nonbreaking spaces count as whitespace, too: Unicode nonbreaking spaces count as whitespace, too:
```````````````````````````````` example ```````````````````````````````` example
* a * * a *
. .
<p>* a *</p> <p>* a *</p>
```````````````````````````````` ````````````````````````````````
Unicode symbols count as punctuation, too:
```````````````````````````````` example
*$*alpha.
*£*bravo.
*€*charlie.
.
<p>*$*alpha.</p>
<p>*£*bravo.</p>
<p>*€*charlie.</p>
````````````````````````````````
Intraword emphasis with `*` is permitted: Intraword emphasis with `*` is permitted:
```````````````````````````````` example ```````````````````````````````` example
foo*bar* foo*bar*
. .
<p>foo<em>bar</em></p> <p>foo<em>bar</em></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
5*6*78 5*6*78
skipping to change at line 6955 skipping to change at line 6965
<p><em>a <code>*</code></em></p> <p><em>a <code>*</code></em></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
_a `_`_ _a `_`_
. .
<p><em>a <code>_</code></em></p> <p><em>a <code>_</code></em></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
**a<http://foo.bar/?q=**> **a<https://foo.bar/?q=**>
. .
<p>**a<a href="http://foo.bar/?q=**">http://foo.bar/?q=**</a></p> <p>**a<a href="https://foo.bar/?q=**">https://foo.bar/?q=**</a></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
__a<http://foo.bar/?q=__> __a<https://foo.bar/?q=__>
. .
<p>__a<a href="http://foo.bar/?q=__">http://foo.bar/?q=__</a></p> <p>__a<a href="https://foo.bar/?q=__">https://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 links] the There are two basic kinds of links in Markdown. In [inline links] the
destination and title are given immediately after the link text. In destination and title are given immediately after the link text. In
[reference links] the destination and title are defined elsewhere in [reference links] the destination and title are defined elsewhere in
the document. the document.
skipping to change at line 7201 skipping to change at line 7211
[link](foo\)\:) [link](foo\)\:)
. .
<p><a href="foo):">link</a></p> <p><a href="foo):">link</a></p>
```````````````````````````````` ````````````````````````````````
A link can contain fragment identifiers and queries: A link can contain fragment identifiers and queries:
```````````````````````````````` example ```````````````````````````````` example
[link](#fragment) [link](#fragment)
[link](http://example.com#fragment) [link](https://example.com#fragment)
[link](http://example.com?foo=3#frag) [link](https://example.com?foo=3#frag)
. .
<p><a href="#fragment">link</a></p> <p><a href="#fragment">link</a></p>
<p><a href="http://example.com#fragment">link</a></p> <p><a href="https://example.com#fragment">link</a></p>
<p><a href="http://example.com?foo=3#frag">link</a></p> <p><a href="https://example.com?foo=3#frag">link</a></p>
```````````````````````````````` ````````````````````````````````
Note that a backslash before a non-escapable character is Note that a backslash before a non-escapable character is
just a backslash: just a backslash:
```````````````````````````````` example ```````````````````````````````` example
[link](foo\bar) [link](foo\bar)
. .
<p><a href="foo%5Cbar">link</a></p> <p><a href="foo%5Cbar">link</a></p>
```````````````````````````````` ````````````````````````````````
skipping to change at line 7426 skipping to change at line 7436
<p>[foo <bar attr="](baz)"></p> <p>[foo <bar attr="](baz)"></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
[foo`](/uri)` [foo`](/uri)`
. .
<p>[foo<code>](/uri)</code></p> <p>[foo<code>](/uri)</code></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
[foo<http://example.com/?search=](uri)> [foo<https://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="https://example.com/?search=%5D(uri)">https://example.com/?searc h=](uri)</a></p>
```````````````````````````````` ````````````````````````````````
There are three kinds of [reference link](@)s: There are three kinds of [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](@) A [full reference link](@)
consists of a [link text] immediately followed by a [link label] consists of a [link text] immediately followed by 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 7570 skipping to change at line 7580
```````````````````````````````` example ```````````````````````````````` example
[foo`][ref]` [foo`][ref]`
[ref]: /uri [ref]: /uri
. .
<p>[foo<code>][ref]</code></p> <p>[foo<code>][ref]</code></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
[foo<http://example.com/?search=][ref]> [foo<https://example.com/?search=][ref]>
[ref]: /uri [ref]: /uri
. .
<p>[foo<a href="http://example.com/?search=%5D%5Bref%5D">http://example.com/?sea rch=][ref]</a></p> <p>[foo<a href="https://example.com/?search=%5D%5Bref%5D">https://example.com/?s earch=][ref]</a></p>
```````````````````````````````` ````````````````````````````````
Matching is case-insensitive: Matching is case-insensitive:
```````````````````````````````` example ```````````````````````````````` example
[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 7759 skipping to change at line 7769
<p>[ <p>[
]</p> ]</p>
<p>[ <p>[
]: /uri</p> ]: /uri</p>
```````````````````````````````` ````````````````````````````````
A [collapsed reference link](@) A [collapsed 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, followed by the string `[]`. document, followed by the string `[]`.
The contents of the first link label are parsed as inlines, The contents of the link label are parsed as inlines,
which are used as the link's text. The link's URI and title are which are used as the link's text. The link's URI and title are
provided by the matching reference link definition. Thus, provided by the matching reference link definition. Thus,
`[foo][]` is equivalent to `[foo][foo]`. `[foo][]` is equivalent to `[foo][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 7807 skipping to change at line 7817
[foo]: /url "title" [foo]: /url "title"
. .
<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 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 7886 skipping to change at line 7896
following closing bracket: following closing bracket:
```````````````````````````````` example ```````````````````````````````` example
[foo*]: /url [foo*]: /url
*[foo*] *[foo*]
. .
<p>*<a href="/url">foo*</a></p> <p>*<a href="/url">foo*</a></p>
```````````````````````````````` ````````````````````````````````
Full and compact references take precedence over shortcut Full and collapsed references take precedence over shortcut
references: references:
```````````````````````````````` example ```````````````````````````````` example
[foo][bar] [foo][bar]
[foo]: /url1 [foo]: /url1
[bar]: /url2 [bar]: /url2
. .
<p><a href="/url2">foo</a></p> <p><a href="/url2">foo</a></p>
```````````````````````````````` ````````````````````````````````
skipping to change at line 8176 skipping to change at line 8186
[Autolink](@)s are absolute URIs and email addresses inside [Autolink](@)s are absolute URIs and email addresses inside
`<` and `>`. They are parsed as links, with the URL or email address `<` and `>`. They are parsed as links, with the URL or email address
as the link label. as the link label.
A [URI autolink](@) consists of `<`, followed by an A [URI autolink](@) consists of `<`, followed by an
[absolute URI] followed by `>`. It is parsed as [absolute URI] followed by `>`. It is parsed as
a link to the URI, with the URI as the link's label. a link to the URI, with the URI as the link's label.
An [absolute URI](@), An [absolute URI](@),
for these purposes, consists of a [scheme] followed by a colon (`:`) for these purposes, consists of a [scheme] followed by a colon (`:`)
followed by zero or more characters other [ASCII control followed by zero or more characters other than [ASCII control
characters][ASCII control character], [space], `<`, and `>`. characters][ASCII control character], [space], `<`, and `>`.
If the URI includes these characters, they must be percent-encoded If the URI includes these characters, they must be percent-encoded
(e.g. `%20` for a space). (e.g. `%20` for a space).
For purposes of this spec, a [scheme](@) is any sequence For purposes of this spec, a [scheme](@) is any sequence
of 2--32 characters beginning with an ASCII letter and followed of 2--32 characters beginning with an ASCII letter and followed
by any combination of ASCII letters, digits, or the symbols plus by any combination of ASCII letters, digits, or the symbols plus
("+"), period ("."), or hyphen ("-"). ("+"), period ("."), or hyphen ("-").
Here are some valid autolinks: Here are some valid autolinks:
```````````````````````````````` example ```````````````````````````````` example
<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>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<http://foo.bar.baz/test?q=hello&id=22&boolean> <https://foo.bar.baz/test?q=hello&id=22&boolean>
. .
<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> <p><a href="https://foo.bar.baz/test?q=hello&amp;id=22&amp;boolean">https://foo. bar.baz/test?q=hello&amp;id=22&amp;boolean</a></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<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 8232 skipping to change at line 8242
<p><a href="a+b+c:d">a+b+c:d</a></p> <p><a href="a+b+c:d">a+b+c:d</a></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<made-up-scheme://foo,bar> <made-up-scheme://foo,bar>
. .
<p><a href="made-up-scheme://foo,bar">made-up-scheme://foo,bar</a></p> <p><a href="made-up-scheme://foo,bar">made-up-scheme://foo,bar</a></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<http://../> <https://../>
. .
<p><a href="http://../">http://../</a></p> <p><a href="https://../">https://../</a></p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<localhost:5001/foo> <localhost:5001/foo>
. .
<p><a href="localhost:5001/foo">localhost:5001/foo</a></p> <p><a href="localhost:5001/foo">localhost:5001/foo</a></p>
```````````````````````````````` ````````````````````````````````
Spaces are not allowed in autolinks: Spaces are not allowed in autolinks:
```````````````````````````````` example ```````````````````````````````` example
<http://foo.bar/baz bim> <https://foo.bar/baz bim>
. .
<p>&lt;http://foo.bar/baz bim&gt;</p> <p>&lt;https://foo.bar/baz bim&gt;</p>
```````````````````````````````` ````````````````````````````````
Backslash-escapes do not work inside autolinks: Backslash-escapes do not work inside autolinks:
```````````````````````````````` example ```````````````````````````````` example
<http://example.com/\[\> <https://example.com/\[\>
. .
<p><a href="http://example.com/%5C%5B%5C">http://example.com/\[\</a></p> <p><a href="https://example.com/%5C%5B%5C">https://example.com/\[\</a></p>
```````````````````````````````` ````````````````````````````````
An [email autolink](@) An [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](@), An [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
skipping to change at line 8303 skipping to change at line 8313
These are not autolinks: These are not autolinks:
```````````````````````````````` example ```````````````````````````````` example
<> <>
. .
<p>&lt;&gt;</p> <p>&lt;&gt;</p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
< http://foo.bar > < https://foo.bar >
. .
<p>&lt; http://foo.bar &gt;</p> <p>&lt; https://foo.bar &gt;</p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<m:abc> <m:abc>
. .
<p>&lt;m:abc&gt;</p> <p>&lt;m:abc&gt;</p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
<foo.bar.baz> <foo.bar.baz>
. .
<p>&lt;foo.bar.baz&gt;</p> <p>&lt;foo.bar.baz&gt;</p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
http://example.com https://example.com
. .
<p>http://example.com</p> <p>https://example.com</p>
```````````````````````````````` ````````````````````````````````
```````````````````````````````` example ```````````````````````````````` example
foo@bar.example.com foo@bar.example.com
. .
<p>foo@bar.example.com</p> <p>foo@bar.example.com</p>
```````````````````````````````` ````````````````````````````````
## Raw HTML ## Raw HTML
skipping to change at line 8383 skipping to change at line 8393
characters not including `"`, and a final `"`. characters not including `"`, and a final `"`.
An [open tag](@) consists of a `<` character, a [tag name], An [open tag](@) consists of a `<` character, a [tag name],
zero or more [attributes], optional spaces, tabs, and up to one line ending, zero or more [attributes], optional spaces, tabs, and up to one line ending,
an optional `/` character, and a `>` character. an optional `/` character, and a `>` character.
A [closing tag](@) consists of the string `</`, a A [closing tag](@) consists of the string `</`, a
[tag name], optional spaces, tabs, and up to one line ending, and the character [tag name], optional spaces, tabs, and up to one line ending, and the character
`>`. `>`.
An [HTML comment](@) consists of `<!--` + *text* + `-->`, An [HTML comment](@) consists of `<!-->`, `<!--->`, or `<!--`, a string of
where *text* does not start with `>` or `->`, does not end with `-`, characters not including the string `-->`, and `-->` (see the
and does not contain `--`. (See the [HTML spec](https://html.spec.whatwg.org/multipage/parsing.html#markup-declarati on-open-state)).
[HTML5 spec](http://www.w3.org/TR/html5/syntax.html#comments).)
A [processing instruction](@) A [processing instruction](@)
consists of the string `<?`, a string consists of the string `<?`, a string
of characters not including the string `?>`, and the string of characters not including the string `?>`, and the string
`?>`. `?>`.
A [declaration](@) consists of the string `<!`, an ASCII letter, zero or more A [declaration](@) consists of the string `<!`, an ASCII letter, zero or more
characters not including the character `>`, and the character `>`. characters not including the character `>`, and the character `>`.
A [CDATA section](@) consists of A [CDATA section](@) consists of
skipping to change at line 8513 skipping to change at line 8522
```````````````````````````````` example ```````````````````````````````` example
</a href="foo"> </a href="foo">
. .
<p>&lt;/a href=&quot;foo&quot;&gt;</p> <p>&lt;/a href=&quot;foo&quot;&gt;</p>
```````````````````````````````` ````````````````````````````````
Comments: Comments:
```````````````````````````````` example ```````````````````````````````` example
foo <!-- this is a foo <!-- this is a --
comment - with hyphen --> comment - with hyphens -->
.
<p>foo <!-- this is a
comment - with hyphen --></p>
````````````````````````````````
```````````````````````````````` example
foo <!-- not a comment -- two hyphens -->
. .
<p>foo <!-- not a comment -- two hyphens --&gt;</p> <p>foo <!-- this is a --
comment - with hyphens --></p>
```````````````````````````````` ````````````````````````````````
Not comments:
```````````````````````````````` example ```````````````````````````````` example
foo <!--> foo --> foo <!--> foo -->
foo <!-- foo---> foo <!---> foo -->
. .
<p>foo <!--&gt; foo --&gt;</p> <p>foo <!--&gt; foo --&gt;</p>
<p>foo <!-- foo---&gt;</p> <p>foo <!---> foo --&gt;</p>
```````````````````````````````` ````````````````````````````````
Processing instructions: Processing instructions:
```````````````````````````````` example ```````````````````````````````` example
foo <?php echo $a; ?> foo <?php echo $a; ?>
. .
<p>foo <?php echo $a; ?></p> <p>foo <?php echo $a; ?></p>
```````````````````````````````` ````````````````````````````````
skipping to change at line 9036 skipping to change at line 9037
Starting at the top of the delimiter stack, we look backwards Starting at the top of the delimiter stack, we look backwards
through the stack for an opening `[` or `![` delimiter. through the stack for an opening `[` or `![` delimiter.
- If we don't find one, we return a literal text node `]`. - If we don't find one, we return a literal text node `]`.
- If we do find one, but it's not *active*, we remove the inactive - If we do find one, but it's not *active*, we remove the inactive
delimiter from the stack, and return a literal text node `]`. delimiter from the stack, and return a literal text node `]`.
- If we find one and it's active, then we parse ahead to see if - If we find one and it's active, then we parse ahead to see if
we have an inline link/image, reference link/image, compact reference we have an inline link/image, reference link/image, collapsed reference
link/image, or shortcut reference link/image. link/image, or shortcut reference link/image.
+ If we don't, then we remove the opening delimiter from the + If we don't, then we remove the opening delimiter from the
delimiter stack and return a literal text node `]`. delimiter stack and return a literal text node `]`.
+ If we do, then + If we do, then
* We return a link or image node whose children are the inlines * We return a link or image node whose children are the inlines
after the text node pointed to by the opening delimiter. after the text node pointed to by the opening delimiter.
 End of changes. 61 change blocks. 
83 lines changed or deleted 84 lines changed or added

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