Foo

. ````````````````````````````````

. ```````````````````````````````` example

[foo]: [foo]:

/url /url

'the title' 'the title'

[foo] [foo]

. .

. ````````````````````````````````

. ```````````````````````````````` example

[Foo*bar\]]:my_(url) 'title (with parens)' [Foo*bar\]]:my_(url) 'title (with parens)'

[Foo*bar\]] [Foo*bar\]]

. .

Foo*bar]

. ````````````````````````````````

. ```````````````````````````````` example

[Foo bar]: [Foo bar]:

url> %20url>

'title' 'title'

[Foo bar] [Foo bar]

. .

Foo bar

. ````````````````````````````````

The title may extend over multiple lines: The title may extend over multiple lines:

. ```````````````````````````````` example

[foo]: /url ' [foo]: /url '

title title

line1 line1

line2 line2

' '

[foo] [foo]

. .

title title

line1 line1

line2 line2

">foo

. ````````````````````````````````

However, it may not contain a [blank line]: However, it may not contain a [blank line]:

. ```````````````````````````````` example

[foo]: /url 'title [foo]: /url 'title

with blank line' with blank line'

[foo] [foo]

. .

[foo]: /url 'title

with blank line'

[foo]

. ````````````````````````````````

The title may be omitted: The title may be omitted:

. ```````````````````````````````` example

[foo]: [foo]:

/url /url

[foo] [foo]

. .

. ````````````````````````````````

The link destination may not be omitted: The link destination may not be omitted:

. ```````````````````````````````` example

[foo]: [foo]:

[foo] [foo]

. .

[foo]:

[foo]

. ````````````````````````````````

Both title and destination can contain backslash escapes Both title and destination can contain backslash escapes

and literal backslashes: and literal backslashes:

. ```````````````````````````````` example

[foo]: /url\bar\*baz "foo\"bar\baz" [foo]: /url\bar\*baz "foo\"bar\baz"

[foo] [foo]

. .

. ````````````````````````````````

A link can come before its corresponding definition: A link can come before its corresponding definition:

. ```````````````````````````````` example

[foo] [foo]

[foo]: url [foo]: url

. .

. ````````````````````````````````

If there are several matching definitions, the first one takes If there are several matching definitions, the first one takes

precedence: precedence:

. ```````````````````````````````` example

[foo] [foo]

[foo]: first [foo]: first

[foo]: second [foo]: second

. .

. ````````````````````````````````

As noted in the section on [Links], matching of labels is As noted in the section on [Links], matching of labels is

case-insensitive (see [matches]). case-insensitive (see [matches]).

. ```````````````````````````````` example

[FOO]: /url [FOO]: /url

[Foo] [Foo]

. .

Foo

. ````````````````````````````````

. ```````````````````````````````` example

[ΑΓΩ]: /φου [ΑΓΩ]: /φου

[αγω] [αγω]

. .

αγω

. ````````````````````````````````

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.

. ```````````````````````````````` example

[foo]: /url [foo]: /url

. .

. ````````````````````````````````

Here is another one: Here is another one:

. ```````````````````````````````` example

[ [

foo foo

]: /url ]: /url

bar bar

. .

bar

. ````````````````````````````````

This is not a link reference definition, because there are This is not a link reference definition, because there are

[non-whitespace character]s after the title: [non-whitespace characters] after the title:

. ```````````````````````````````` example

[foo]: /url "title" ok [foo]: /url "title" ok

. .

[foo]: /url "title" ok

. ````````````````````````````````

This is a link reference definition, but it has no title: This is a link reference definition, but it has no title:

. ```````````````````````````````` example

[foo]: /url [foo]: /url

"title" ok "title" ok

. .

"title" ok

. ````````````````````````````````

This is not a link reference definition, because it is indented This is not a link reference definition, because it is indented

four spaces: four spaces:

. ```````````````````````````````` example

[foo]: /url "title" [foo]: /url "title"

[foo] [foo]

. .

[foo]: /url "title"

[foo]: /url "title"

[foo]

. ````````````````````````````````

This is not a link reference definition, because it occurs inside This is not a link reference definition, because it occurs inside

a code block: a code block:

. ```````````````````````````````` example

``` ```

[foo]: /url [foo]: /url

``` ```

[foo] [foo]

. .

[foo]: /url

[foo]: /url

[foo]

. ````````````````````````````````

A [link reference definition] cannot interrupt a paragraph. A [link reference definition] cannot interrupt a paragraph.

. ```````````````````````````````` example

Foo Foo

[bar]: /baz [bar]: /baz

[bar] [bar]

. .

Foo

[bar]: /baz

[bar]

. ````````````````````````````````

However, it can directly follow other block elements, such as headings However, it can directly follow other block elements, such as headings

and thematic breaks, and it need not be followed by a blank line. and thematic breaks, and it need not be followed by a blank line.

. ```````````````````````````````` example

# [Foo] # [Foo]

[foo]: /url [foo]: /url

> bar > bar

. .

Foo

bar

. ````````````````````````````````

Several [link reference definition]s Several [link reference definitions]

can occur one after another, without intervening blank lines. can occur one after another, without intervening blank lines.

. ```````````````````````````````` example

[foo]: /foo-url "foo" [foo]: /foo-url "foo"

[bar]: /bar-url [bar]: /bar-url

"bar" "bar"

[baz]: /baz-url [baz]: /baz-url

[foo], [foo],

[bar], [bar],

[baz] [baz]

. .

foo,

bar, bar,

baz

. ````````````````````````````````

[Link reference definition]s can occur [Link reference definitions] can occur

inside block containers, like lists and block quotations. They inside block containers, like lists and block quotations. They

affect the entire document, not just the container in which they affect the entire document, not just the container in which they

are defined: are defined:

. ```````````````````````````````` example

[foo] [foo]

> [foo]: /url > [foo]: /url

. .

http://example.com?find=\*

. ````````````````````````````````

## Paragraphs ## Paragraphs

A sequence of non-blank lines that cannot be interpreted as other A sequence of non-blank lines that cannot be interpreted as other

kinds of blocks forms a [paragraph](@paragraph). kinds of blocks forms a [paragraph](@).

The contents of the paragraph are the result of parsing the The contents of the paragraph are the result of parsing the

paragraph's raw content as inlines. The paragraph's raw content paragraph's raw content as inlines. The paragraph's raw content

is formed by concatenating the lines and removing initial and final is formed by concatenating the lines and removing initial and final

[whitespace]. [whitespace].

A simple example with two paragraphs: A simple example with two paragraphs:

. ```````````````````````````````` example

aaa aaa

bbb bbb

. .

aaa

bbb

. ````````````````````````````````

Paragraphs can contain multiple lines, but no blank lines: Paragraphs can contain multiple lines, but no blank lines:

. ```````````````````````````````` example

aaa aaa

bbb bbb

ccc ccc

ddd ddd

. .

aaa

bbb

ccc

ddd

. ````````````````````````````````

Multiple blank lines between paragraph have no effect: Multiple blank lines between paragraph have no effect:

. ```````````````````````````````` example

aaa aaa

bbb bbb

. .

aaa

bbb

. ````````````````````````````````

Leading spaces are skipped: Leading spaces are skipped:

. ```````````````````````````````` example

aaa aaa

bbb bbb

. .

aaa

bbb

. ````````````````````````````````

Lines after the first may be indented any amount, since indented Lines after the first may be indented any amount, since indented

code blocks cannot interrupt paragraphs. code blocks cannot interrupt paragraphs.

. ```````````````````````````````` example

aaa aaa

bbb bbb

ccc ccc

. .

aaa

bbb bbb

ccc

. ````````````````````````````````

However, the first line may be indented at most three spaces, However, the first line may be indented at most three spaces,

or an indented code block will be triggered: or an indented code block will be triggered:

. ```````````````````````````````` example

aaa aaa

bbb bbb

. .

aaa

bbb

. ````````````````````````````````

. ```````````````````````````````` example

aaa aaa

bbb bbb

. .

aaa

aaa

bbb

. ````````````````````````````````

Final spaces are stripped before inline parsing, so a paragraph Final spaces are stripped before inline parsing, so a paragraph

that ends with two or more spaces will not end with a [hard line that ends with two or more spaces will not end with a [hard line

break]: break]:

. ```````````````````````````````` example

aaa aaa

bbb bbb

. .

aaa

bbb

. ````````````````````````````````

## Blank lines ## Blank lines

[Blank line]s between block-level elements are ignored, [Blank lines] between block-level elements are ignored,

except for the role they play in determining whether a [list] except for the role they play in determining whether a [list]

is [tight] or [loose]. is [tight] or [loose].

Blank lines at the beginning and end of the document are also ignored. Blank lines at the beginning and end of the document are also ignored.

. ```````````````````````````````` example

aaa aaa

# aaa # aaa

. .

aaa

. ````````````````````````````````

# Container blocks # Container blocks

A [container block] is a block that has other A [container block] is a block that has other

blocks as its contents. There are two basic kinds of container blocks: blocks as its contents. There are two basic kinds of container blocks:

[block quotes] and [list items]. [block quotes] and [list items].

[Lists] are meta-containers for [list items]. [Lists] are meta-containers for [list items].

We define the syntax for container blocks recursively. The general We define the syntax for container blocks recursively. The general

form of the definition is: form of the definition is:

skipping to change at line 2733 skipping to change at line 2833

> with these blocks as its content. > with these blocks as its content.

So, we explain what counts as a block quote or list item by explaining So, we explain what counts as a block quote or list item by explaining

how these can be *generated* from their contents. This should suffice how these can be *generated* from their contents. This should suffice

to define the syntax, although it does not give a recipe for *parsing* to define the syntax, although it does not give a recipe for *parsing*

these constructions. (A recipe is provided below in the section entitled these constructions. (A recipe is provided below in the section entitled

[A parsing strategy](#appendix-a-parsing-strategy).) [A parsing strategy](#appendix-a-parsing-strategy).)

## Block quotes ## Block quotes

A [block quote marker](@block-quote-marker) A [block quote marker](@)

consists of 0-3 spaces of initial indent, plus (a) the character `>` together consists of 0-3 spaces of initial indent, plus (a) the character `>` together

with a following space, or (b) a single character `>` not followed by a space. with a following space, or (b) a single character `>` not followed by a space.

The following rules define [block quotes]: The following rules define [block quotes]:

1. **Basic case.** If a string of lines *Ls* constitute a sequence 1. **Basic case.** If a string of lines *Ls* constitute a sequence

of blocks *Bs*, then the result of prepending a [block quote of blocks *Bs*, then the result of prepending a [block quote

marker] to the beginning of each line in *Ls* marker] to the beginning of each line in *Ls*

is a [block quote](#block-quotes) containing *Bs*. is a [block quote](#block-quotes) containing *Bs*.

2. **Laziness.** If a string of lines *Ls* constitute a [block 2. **Laziness.** If a string of lines *Ls* constitute a [block

quote](#block-quotes) with contents *Bs*, then the result of deleting quote](#block-quotes) with contents *Bs*, then the result of deleting

the initial [block quote marker] from one or the initial [block quote marker] from one or

more lines in which the next [non-whitespace character] after the [block more lines in which the next [non-whitespace character] after the [block

quote marker] is [paragraph continuation quote marker] is [paragraph continuation

text] is a block quote with *Bs* as its content. text] is a block quote with *Bs* as its content.

[Paragraph continuation text](@paragraph-continuation-text) is text [Paragraph continuation text](@) is text

that will be parsed as part of the content of a paragraph, but does that will be parsed as part of the content of a paragraph, but does

not occur at the beginning of the paragraph. not occur at the beginning of the paragraph.

3. **Consecutiveness.** A document cannot contain two [block 3. **Consecutiveness.** A document cannot contain two [block

quotes] in a row unless there is a [blank line] between them. quotes] in a row unless there is a [blank line] between them.

Nothing else counts as a [block quote](#block-quotes). Nothing else counts as a [block quote](#block-quotes).

Here is a simple example: Here is a simple example:

. ```````````````````````````````` example

> # Foo > # Foo

> bar > bar

> baz > baz

. .

Foo

bar

baz

. ````````````````````````````````

The spaces after the `>` characters can be omitted: The spaces after the `>` characters can be omitted:

. ```````````````````````````````` example

># Foo ># Foo

>bar >bar

> baz > baz

. .

Foo

bar

baz

. ````````````````````````````````

The `>` characters can be indented 1-3 spaces: The `>` characters can be indented 1-3 spaces:

. ```````````````````````````````` example

> # Foo > # Foo

> bar > bar

> baz > baz

. .

Foo

bar

baz

. ````````````````````````````````

Four spaces gives us a code block: Four spaces gives us a code block:

. ```````````````````````````````` example

> # Foo > # Foo

> bar > bar

> baz > baz

. .

> # Foo

> # Foo

> bar > bar

> baz > baz

. ````````````````````````````````

The Laziness clause allows us to omit the `>` before a The Laziness clause allows us to omit the `>` before a

paragraph continuation line: paragraph continuation line:

. ```````````````````````````````` example

> # Foo > # Foo

> bar > bar

baz baz

. .

Foo

bar

baz

. ````````````````````````````````

A block quote can contain some lazy and some non-lazy A block quote can contain some lazy and some non-lazy

continuation lines: continuation lines:

. ```````````````````````````````` example

> bar > bar

baz baz

> foo > foo

. .

bar

baz baz

foo

. ````````````````````````````````

Laziness only applies to lines that would have been continuations of Laziness only applies to lines that would have been continuations of

paragraphs had they been prepended with [block quote marker]s. paragraphs had they been prepended with [block quote markers].

For example, the `> ` cannot be omitted in the second line of For example, the `> ` cannot be omitted in the second line of

``` markdown ``` markdown

> foo > foo

> --- > ---

``` ```

without changing the meaning: without changing the meaning:

. ```````````````````````````````` example

> foo > foo

--- ---

. .

foo

. ````````````````````````````````

Similarly, if we omit the `> ` in the second line of Similarly, if we omit the `> ` in the second line of

``` markdown ``` markdown

> - foo > - foo

> - bar > - bar

``` ```

then the block quote ends after the first line: then the block quote ends after the first line:

. ```````````````````````````````` example

> - foo > - foo

- bar - bar

. .

foo foo

bar bar

. ````````````````````````````````

For the same reason, we can't omit the `> ` in front of For the same reason, we can't omit the `> ` in front of

subsequent lines of an indented or fenced code block: subsequent lines of an indented or fenced code block:

. ```````````````````````````````` example

> foo > foo

bar bar

. .

foo

foo

bar

bar

. ````````````````````````````````

. ```````````````````````````````` example

> ``` > ```

foo foo

``` ```

. .

foo

. ````````````````````````````````

Note that in the following case, we have a paragraph Note that in the following case, we have a paragraph

continuation line: continuation line:

. ```````````````````````````````` example

> foo > foo

- bar - bar

. .

foo

- bar

. ````````````````````````````````

To see why, note that in To see why, note that in

```markdown ```markdown

> foo > foo

> - bar > - bar

``` ```

the `- bar` is indented too far to start a list, and can't the `- bar` is indented too far to start a list, and can't

be an indented code block because indented code blocks cannot be an indented code block because indented code blocks cannot

interrupt paragraphs, so it is a [paragraph continuation line]. interrupt paragraphs, so it is a [paragraph continuation line].

A block quote can be empty: A block quote can be empty:

. ```````````````````````````````` example

> >

. .

. ````````````````````````````````

. ```````````````````````````````` example

> >

. .

. ````````````````````````````````

A block quote can have initial or final blank lines: A block quote can have initial or final blank lines:

. ```````````````````````````````` example

> >

> foo > foo

> >

. .

foo

. ````````````````````````````````

A blank line always separates block quotes: A blank line always separates block quotes:

. ```````````````````````````````` example

> foo > foo

> bar > bar

. .

foo

bar

. ````````````````````````````````

(Most current Markdown implementations, including John Gruber's (Most current Markdown implementations, including John Gruber's

original `Markdown.pl`, will parse this example as a single block quote original `Markdown.pl`, will parse this example as a single block quote

with two paragraphs. But it seems better to allow the author to decide with two paragraphs. But it seems better to allow the author to decide

whether two block quotes or one are wanted.) whether two block quotes or one are wanted.)

Consecutiveness means that if we put these block quotes together, Consecutiveness means that if we put these block quotes together,

we get a single block quote: we get a single block quote:

. ```````````````````````````````` example

> foo > foo

> bar > bar

. .

foo

bar

. ````````````````````````````````

To get a block quote with two paragraphs, use: To get a block quote with two paragraphs, use:

. ```````````````````````````````` example

> foo > foo

> >

> bar > bar

. .

foo

bar

. ````````````````````````````````

Block quotes can interrupt paragraphs: Block quotes can interrupt paragraphs:

. ```````````````````````````````` example

foo foo

> bar > bar

. .

foo

bar

. ````````````````````````````````

In general, blank lines are not needed before or after block In general, blank lines are not needed before or after block

quotes: quotes:

. ```````````````````````````````` example

> aaa > aaa

*** ***

> bbb > bbb

. .

aaa

bbb

. ````````````````````````````````

However, because of laziness, a blank line is needed between However, because of laziness, a blank line is needed between

a block quote and a following paragraph: a block quote and a following paragraph:

. ```````````````````````````````` example

> bar > bar

baz baz

. .

bar

baz

. ````````````````````````````````

. ```````````````````````````````` example

> bar > bar

baz baz

. .

bar

baz

. ````````````````````````````````

. ```````````````````````````````` example

> bar > bar

> >

baz baz

. .

bar

baz

. ````````````````````````````````

It is a consequence of the Laziness rule that any number It is a consequence of the Laziness rule that any number

of initial `>`s may be omitted on a continuation line of a of initial `>`s may be omitted on a continuation line of a

nested block quote: nested block quote:

. ```````````````````````````````` example

> > > foo > > > foo

bar bar

. .

foo

bar

. ````````````````````````````````

. ```````````````````````````````` example

>>> foo >>> foo

> bar > bar

>>baz >>baz

. .

foo

bar bar

baz

. ````````````````````````````````

When including an indented code block in a block quote, When including an indented code block in a block quote,

remember that the [block quote marker] includes remember that the [block quote marker] includes

both the `>` and a following space. So *five spaces* are needed after both the `>` and a following space. So *five spaces* are needed after

the `>`: the `>`:

. ```````````````````````````````` example

> code > code

> not code > not code

. .

code

code

not code

. ````````````````````````````````

## List items ## List items

A [list marker](@list-marker) is a A [list marker](@) is a

[bullet list marker] or an [ordered list marker]. [bullet list marker] or an [ordered list marker].

A [bullet list marker](@bullet-list-marker) A [bullet list marker](@)

is a `-`, `+`, or `*` character. is a `-`, `+`, or `*` character.

An [ordered list marker](@ordered-list-marker) An [ordered list marker](@)

is a sequence of 1--9 arabic digits (`0-9`), followed by either a is a sequence of 1--9 arabic digits (`0-9`), followed by either a

`.` character or a `)` character. (The reason for the length `.` character or a `)` character. (The reason for the length

limit is that with 10 digits we start seeing integer overflows limit is that with 10 digits we start seeing integer overflows

in some browsers.) in some browsers.)

The following rules define [list items]: The following rules define [list items]:

1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of 1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of

blocks *Bs* starting with a [non-whitespace character] and not separated blocks *Bs* starting with a [non-whitespace character] and not separated

from each other by more than one blank line, and *M* is a list from each other by more than one blank line, and *M* is a list

marker of width *W* followed by 0 < *N* < 5 spaces, then the result marker of width *W* followed by 0 < *N* < 5 spaces, then the result

of prepending *M* and the following spaces to the first line of of prepending *M* and the following spaces to the first line of

*Ls*, and indenting subsequent lines of *Ls* by *W + N* spaces, is a *Ls*, and indenting subsequent lines of *Ls* by *W + N* spaces, is a

list item with *Bs* as its contents. The type of the list item list item with *Bs* as its contents. The type of the list item

(bullet or ordered) is determined by the type of its list marker. (bullet or ordered) is determined by the type of its list marker.

If the list item is ordered, then it is also assigned a start If the list item is ordered, then it is also assigned a start

number, based on the ordered list marker. number, based on the ordered list marker.

For example, let *Ls* be the lines For example, let *Ls* be the lines

. ```````````````````````````````` example

A paragraph A paragraph

with two lines. with two lines.

indented code indented code

> A block quote. > A block quote.

. .

A paragraph

with two lines.

indented code

indented code

A block quote.

. ````````````````````````````````

And let *M* be the marker `1.`, and *N* = 2. Then rule #1 says And let *M* be the marker `1.`, and *N* = 2. Then rule #1 says

that the following is an ordered list item with start number 1, that the following is an ordered list item with start number 1,

and the same contents as *Ls*: and the same contents as *Ls*:

. ```````````````````````````````` example

1. A paragraph 1. A paragraph

with two lines. with two lines.

indented code indented code

> A block quote. > A block quote.

. .

A paragraph

with two lines.

indented code

indented code

A block quote.

. ````````````````````````````````

The most important thing to notice is that the position of The most important thing to notice is that the position of

the text after the list marker determines how much indentation the text after the list marker determines how much indentation

is needed in subsequent blocks in the list item. If the list is needed in subsequent blocks in the list item. If the list

marker takes up two spaces, and there are three spaces between marker takes up two spaces, and there are three spaces between

the list marker and the next [non-whitespace character], then blocks the list marker and the next [non-whitespace character], then blocks

must be indented five spaces in order to fall under the list must be indented five spaces in order to fall under the list

item. item.

Here are some examples showing how far content must be indented to be Here are some examples showing how far content must be indented to be

put under the list item: put under the list item:

. ```````````````````````````````` example

- one - one

two two

. .

one one

two

. ````````````````````````````````

. ```````````````````````````````` example

- one - one

two two

. .

one

two

. ````````````````````````````````

. ```````````````````````````````` example

- one - one

two two

. .

one one

two

two

. ````````````````````````````````

. ```````````````````````````````` example

- one - one

two two

. .

one

two

. ````````````````````````````````

It is tempting to think of this in terms of columns: the continuation It is tempting to think of this in terms of columns: the continuation

blocks must be indented at least to the column of the first blocks must be indented at least to the column of the first

[non-whitespace character] after the list marker. However, that is not quite rig ht. [non-whitespace character] after the list marker. However, that is not quite rig ht.

The spaces after the list marker determine how much relative indentation The spaces after the list marker determine how much relative indentation

is needed. Which column this indentation reaches will depend on is needed. Which column this indentation reaches will depend on

how the list item is embedded in other constructions, as shown by how the list item is embedded in other constructions, as shown by

this example: this example:

. ```````````````````````````````` example

> > 1. one > > 1. one

>> >>

>> two >> two

. .

one

two

. ````````````````````````````````

Here `two` occurs in the same column as the list marker `1.`, Here `two` occurs in the same column as the list marker `1.`,

but is actually contained in the list item, because there is but is actually contained in the list item, because there is

sufficient indentation after the last containing blockquote marker. sufficient indentation after the last containing blockquote marker.

The converse is also possible. In the following example, the word `two` The converse is also possible. In the following example, the word `two`

occurs far to the right of the initial text of the list item, `one`, but occurs far to the right of the initial text of the list item, `one`, but

it is not considered part of the list item, because it is not indented it is not considered part of the list item, because it is not indented

far enough past the blockquote marker: far enough past the blockquote marker:

. ```````````````````````````````` example

>>- one >>- one

>> >>

> > two > > two

. .

one one

two

. ````````````````````````````````

Note that at least one space is needed between the list marker and Note that at least one space is needed between the list marker and

any following content, so these are not list items: any following content, so these are not list items:

. ```````````````````````````````` example

-one -one

2.two 2.two

. .

-one

2.two

. ````````````````````````````````

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].

. ```````````````````````````````` example

- foo - foo

bar bar

- foo - foo

bar bar

- ``` - ```

foo foo

skipping to change at line 3380 skipping to change at line 3480

foo

foo

bar bar

. ````````````````````````````````

A list item may contain any kind of block: A list item may contain any kind of block:

. ```````````````````````````````` example

1. foo 1. foo

``` ```

bar bar

``` ```

baz baz

> bam > bam

. .

skipping to change at line 3406 skipping to change at line 3506

foo

bar

bar

baz

bam

. ````````````````````````````````

A list item that contains an indented code block will preserve A list item that contains an indented code block will preserve

empty lines within the code block verbatim, unless there are two empty lines within the code block verbatim, unless there are two

or more empty lines in a row (since as described above, two or more empty lines in a row (since as described above, two

blank lines end the list): blank lines end the list):

. ```````````````````````````````` example

- Foo - Foo

bar bar

baz baz

. .

Foo

bar

bar

baz baz

. ````````````````````````````````

. ```````````````````````````````` example

- Foo - Foo

bar bar

baz baz

. .

Foo

bar

bar

baz

baz

. ````````````````````````````````

Note that ordered list start numbers must be nine digits or less: Note that ordered list start numbers must be nine digits or less:

. ```````````````````````````````` example

123456789. ok 123456789. ok

. .

ok ok

. ````````````````````````````````

. ```````````````````````````````` example

1234567890. not ok 1234567890. not ok

. .

1234567890. not ok

. ````````````````````````````````

A start number may begin with 0s: A start number may begin with 0s:

. ```````````````````````````````` example

0. ok 0. ok

. .

ok ok

. ````````````````````````````````

. ```````````````````````````````` example

003. ok 003. ok

. .

ok ok

. ````````````````````````````````

A start number may not be negative: A start number may not be negative:

. ```````````````````````````````` example

-1. not ok -1. not ok

. .

-1. not ok

. ````````````````````````````````

2. **Item starting with indented code.** If a sequence of lines *Ls* 2. **Item starting with indented code.** If a sequence of lines *Ls*

constitute a sequence of blocks *Bs* starting with an indented code constitute a sequence of blocks *Bs* starting with an indented code

block and not separated from each other by more than one blank line, block and not separated from each other by more than one blank line,

and *M* is a list marker of width *W* followed by and *M* is a list marker of width *W* followed by

one space, then the result of prepending *M* and the following one space, then the result of prepending *M* and the following

space to the first line of *Ls*, and indenting subsequent lines of space 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. *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 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 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 marker. If the list item is ordered, then it is also assigned a

start number, based on the ordered list marker. start number, based on the ordered list marker.

An indented code block will have to be indented four spaces beyond An indented code block will have to be indented four spaces beyond

the edge of the region where text will be included in the list item. the edge of the region where text will be included in the list item.

In the following case that is 6 spaces: In the following case that is 6 spaces:

. ```````````````````````````````` example

- foo - foo

bar bar

. .

foo

bar

bar

. ````````````````````````````````

And in this case it is 11 spaces: And in this case it is 11 spaces:

. ```````````````````````````````` example

10. foo 10. foo

bar bar

. .

foo

bar

bar

. ````````````````````````````````

If the *first* block in the list item is an indented code block, If the *first* block in the list item is an indented code block,

then by rule #2, the contents must be indented *one* space after the then by rule #2, the contents must be indented *one* space after the

list marker: list marker:

. ```````````````````````````````` example

indented code indented code

paragraph paragraph

more code more code

. .

indented code

indented code

paragraph

more code

more code

. ````````````````````````````````

. ```````````````````````````````` example

1. indented code 1. indented code

paragraph paragraph

more code more code

. .

indented code

indented code

paragraph

more code

more code

. ````````````````````````````````

Note that an additional space indent is interpreted as space Note that an additional space indent is interpreted as space

inside the code block: inside the code block:

. ```````````````````````````````` example

1. indented code 1. indented code

paragraph paragraph

more code more code

. .

 indented code

 indented code

paragraph

more code

more code

. ````````````````````````````````

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

[non-whitespace character], and (b) cases in which [non-whitespace character], 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

a three-space indent, the rules do not allow us to form a list item by a three-space indent, 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

foo foo

bar bar

. .

foo

bar

. ````````````````````````````````

. ```````````````````````````````` example

- foo - foo

bar bar

. .

foo foo

bar

. ````````````````````````````````

This is not a significant restriction, because when a block begins This is not a significant restriction, because when a block begins

with 1-3 spaces indent, the indentation can always be removed without with 1-3 spaces indent, the indentation can always be removed without

a change in interpretation, allowing rule #1 to be applied. So, in a change in interpretation, allowing rule #1 to be applied. So, in

the above case: the above case:

. ```````````````````````````````` example

- foo - foo

bar bar

. .

foo

bar

. ````````````````````````````````

3. **Item starting with a blank line.** If a sequence of lines *Ls* 3. **Item starting with a blank line.** If a sequence of lines *Ls*

starting with a single [blank line] constitute a (possibly empty) starting with a single [blank line] constitute a (possibly empty)

sequence of blocks *Bs*, not separated from each other by more than sequence of blocks *Bs*, not separated from each other by more than

one blank line, and *M* is a list marker of width *W*, one blank line, and *M* is a list marker of width *W*,

then the result of prepending *M* to the first line of *Ls*, and 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 indenting subsequent lines of *Ls* by *W + 1* spaces, is a list

item with *Bs* as its contents. item with *Bs* as its contents.

If a line is empty, then it need not be indented. The type of the 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 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 marker. If the list item is ordered, then it is also assigned a

start number, based on the ordered list marker. start number, based on the ordered list marker.

Here are some list items that start with a blank line but are not empty: Here are some list items that start with a blank line but are not empty:

. ```````````````````````````````` example

- -

foo foo

- -

``` ```

bar bar

``` ```

- -

baz baz

. .

foo foo

bar

bar

baz

baz

. ````````````````````````````````

A list item can begin with at most one blank line. A list item can begin with at most one blank line.

In the following example, `foo` is not part of the list In the following example, `foo` is not part of the list

item: item:

. ```````````````````````````````` example

- -

foo foo

. .

foo

. ````````````````````````````````

Here is an empty bullet list item: Here is an empty bullet list item:

. ```````````````````````````````` example

- foo - foo

- -

- bar - bar

. .

foo foo

bar bar

. ````````````````````````````````

It does not matter whether there are spaces following the [list marker]: It does not matter whether there are spaces following the [list marker]:

. ```````````````````````````````` example

- foo - foo

- -

- bar - bar

. .

foo foo

bar bar

. ````````````````````````````````

Here is an empty ordered list item: Here is an empty ordered list item:

. ```````````````````````````````` example

1. foo 1. foo

2. 2.

3. bar 3. bar

. .

foo foo

bar bar

. ````````````````````````````````

A list may start or end with an empty list item: A list may start or end with an empty list item:

. ```````````````````````````````` example

* *

. .

. ````````````````````````````````

4. **Indentation.** If a sequence of lines *Ls* constitutes a list item 4. **Indentation.** If a sequence of lines *Ls* constitutes a list item

according to rule #1, #2, or #3, then the result of indenting each line according to rule #1, #2, or #3, then the result of indenting each line

of *Ls* by 1-3 spaces (the same for each line) also constitutes a of *Ls* by 1-3 spaces (the same for each line) also constitutes a

list item with the same contents and attributes. If a line is list item with the same contents and attributes. If a line is

empty, then it need not be indented. empty, then it need not be indented.

Indented one space: Indented one space:

. ```````````````````````````````` example

1. A paragraph 1. A paragraph

with two lines. with two lines.

indented code indented code

> A block quote. > A block quote.

. .

A paragraph

with two lines.

indented code

indented code

A block quote.

. ````````````````````````````````

Indented two spaces: Indented two spaces:

. ```````````````````````````````` example

1. A paragraph 1. A paragraph

with two lines. with two lines.

indented code indented code

> A block quote. > A block quote.

. .

A paragraph

with two lines.

indented code

indented code

A block quote.

. ````````````````````````````````

Indented three spaces: Indented three spaces:

. ```````````````````````````````` example

1. A paragraph 1. A paragraph

with two lines. with two lines.

indented code indented code

> A block quote. > A block quote.

. .

A paragraph

with two lines.

indented code

indented code

A block quote.

. ````````````````````````````````

Four spaces indent gives a code block: Four spaces indent gives a code block:

. ```````````````````````````````` example

1. A paragraph 1. A paragraph

with two lines. with two lines.

indented code indented code

> A block quote. > A block quote.

. .

1.  A paragraph

1.  A paragraph

with two lines. with two lines.

indented code indented code

> A block quote. > A block quote.

. ````````````````````````````````

5. **Laziness.** If a string of lines *Ls* constitute a [list 5. **Laziness.** If a string of lines *Ls* constitute a [list

item](#list-items) with contents *Bs*, then the result of deleting item](#list-items) with contents *Bs*, then the result of deleting

some or all of the indentation from one or more lines in which the some or all of the indentation from one or more lines in which the

next [non-whitespace character] after the indentation is next [non-whitespace character] after the indentation is

[paragraph continuation text] is a [paragraph continuation text] is a

list item with the same contents and attributes. The unindented list item with the same contents and attributes. The unindented

lines are called lines are called

[lazy continuation line](@lazy-continuation-line)s. [lazy continuation line](@)s.

Here is an example with [lazy continuation line]s: Here is an example with [lazy continuation lines]:

. ```````````````````````````````` example

1. A paragraph 1. A paragraph

with two lines. with two lines.

indented code indented code

> A block quote. > A block quote.

. .

A paragraph

with two lines.

indented code

indented code

A block quote.

. ````````````````````````````````

Indentation can be partially deleted: Indentation can be partially deleted:

. ```````````````````````````````` example

1. A paragraph 1. A paragraph

with two lines. with two lines.

. .

A paragraph A paragraph

with two lines. with two lines.

. ````````````````````````````````

These examples show how laziness can work in nested structures: These examples show how laziness can work in nested structures:

. ```````````````````````````````` example

> 1. > Blockquote > 1. > Blockquote

continued here. continued here.

. .

Blockquote

continued here.

. ````````````````````````````````

. ```````````````````````````````` example

> 1. > Blockquote > 1. > Blockquote

> continued here. > continued here.

. .

Blockquote

continued here.

. ````````````````````````````````

6. **That's all.** Nothing that is not counted as a list item by rules 6. **That's all.** Nothing that is not counted as a list item by rules

#1--5 counts as a [list item](#list-items). #1--5 counts as a [list item](#list-items).

The rules for sublists follow from the general rules above. A sublist The rules for sublists follow from the general rules above. A sublist

must be indented the same number of spaces a paragraph would need to be must be indented the same number of spaces a paragraph would need to be

in order to be included in the list item. in order to be included in the list item.

So, in this case we need two spaces indent: So, in this case we need two spaces indent:

. ```````````````````````````````` example

- foo - foo

- bar - bar

- baz - baz

. .

foo foo

bar bar

baz baz

. ````````````````````````````````

One is not enough: One is not enough:

. ```````````````````````````````` example

- foo - foo

- bar - bar

- baz - baz

. .

foo foo

bar bar

baz baz

. ````````````````````````````````

Here we need four, because the list marker is wider: Here we need four, because the list marker is wider:

. ```````````````````````````````` example

10) foo 10) foo

- bar - bar

. .

foo foo

bar bar

. ````````````````````````````````

Three is not enough: Three is not enough:

. ```````````````````````````````` example

10) foo 10) foo

- bar - bar

. .

foo foo

bar bar

. ````````````````````````````````

A list may be the first block in a list item: A list may be the first block in a list item:

. ```````````````````````````````` example

- - foo - - foo

. .

foo foo

. ````````````````````````````````

. ```````````````````````````````` example

1. - 2. foo 1. - 2. foo

. .

foo foo

. ````````````````````````````````

A list item can contain a heading: A list item can contain a heading:

. ```````````````````````````````` example

- # Foo - # Foo

- Bar - Bar

--- ---

baz baz

. .

Foo

Bar

baz baz

. ````````````````````````````````

### Motivation ### Motivation

John Gruber's Markdown spec says the following about list items: John Gruber's Markdown spec says the following about list items:

1. "List markers typically start at the left margin, but may be indented 1. "List markers typically start at the left margin, but may be indented

by up to three spaces. List markers must be followed by one or more by up to three spaces. List markers must be followed by one or more

spaces or a tab." spaces or a tab."

2. "To make lists look nice, you can wrap items with hanging indents.... 2. "To make lists look nice, you can wrap items with hanging indents....

skipping to change at line 4222 skipping to change at line 4322

The one case that needs special treatment is a list item that *starts* The one case that needs special treatment is a list item that *starts*

with indented code. How much indentation is required in that case, since with indented code. How much indentation is required in that case, since

we don't have a "first paragraph" to measure from? Rule #2 simply stipulates we don't have a "first paragraph" to measure from? Rule #2 simply stipulates

that in such cases, we require one space indentation from the list marker that in such cases, we require one space indentation from the list marker

(and then the normal four spaces for the indented code). This will match the (and then the normal four spaces for the indented code). This will match the

four-space rule in cases where the list marker plus its initial indentation four-space rule in cases where the list marker plus its initial indentation

takes four spaces (a common case), but diverge in other cases. takes four spaces (a common case), but diverge in other cases.

## Lists ## Lists

A [list](@list) is a sequence of one or more A [list](@) is a sequence of one or more

list items [of the same type]. The list items list items [of the same type]. The list items

may be separated by single [blank lines], but two may be separated by single [blank lines], but two

blank lines end all containing lists. blank lines end all containing lists.

Two list items are [of the same type](@of-the-same-type) Two list items are [of the same type](@)

if they begin with a [list marker] of the same type. if they begin with a [list marker] of the same type.

Two list markers are of the Two list markers are of the

same type if (a) they are bullet list markers using the same character same type if (a) they are bullet list markers using the same character

(`-`, `+`, or `*`) or (b) they are ordered list numbers with the same (`-`, `+`, or `*`) or (b) they are ordered list numbers with the same

delimiter (either `.` or `)`). delimiter (either `.` or `)`).

A list is an [ordered list](@ordered-list) A list is an [ordered list](@)

if its constituent list items begin with if its constituent list items begin with

[ordered list marker]s, and a [ordered list markers], and a

[bullet list](@bullet-list) if its constituent list [bullet list](@) if its constituent list

items begin with [bullet list marker]s. items begin with [bullet list markers].

The [start number](@start-number) The [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 any of its constituent A list is [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](@).

(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 `

` tags, while paragraphs in a tight list are not.)

wrapped in `

` 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:

. ```````````````````````````````` example

- foo - foo

- bar - bar

+ baz + baz

. .

foo foo

bar bar

baz baz

. ````````````````````````````````

. ```````````````````````````````` example

1. foo 1. foo

2. bar 2. bar

3) baz 3) baz

. .

foo foo

bar bar

baz baz

. ````````````````````````````````

In CommonMark, a list can interrupt a paragraph. That is, In CommonMark, a list can interrupt a paragraph. That is,

no blank line is needed to separate a paragraph from a following no blank line is needed to separate a paragraph from a following

list: list:

. ```````````````````````````````` example

Foo Foo

- bar - bar

- baz - baz

. .

Foo

bar bar

baz baz

. ````````````````````````````````

`Markdown.pl` does not allow this, through fear of triggering a list `Markdown.pl` does not allow this, through fear of triggering a list

via a numeral in a hard-wrapped line: via a numeral in a hard-wrapped line:

. ```````````````````````````````` example

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.

. .

The number of windows in my house is

The number of doors is 6. The number of doors is 6.

. ````````````````````````````````

Oddly, `Markdown.pl` *does* allow a blockquote to interrupt a paragraph, Oddly, `Markdown.pl` *does* allow a blockquote to interrupt a paragraph,

even though the same considerations might apply. We think that the two even though the same considerations might apply. We think that the two

cases should be treated the same. Here are two reasons for allowing cases should be treated the same. Here are two reasons for allowing

lists to interrupt paragraphs: lists to interrupt paragraphs:

First, it is natural and not uncommon for people to start lists without First, it is natural and not uncommon for people to start lists without

blank lines: blank lines:

I need to buy I need to buy

- new shoes - new shoes

- a coat - a coat

- a plane ticket - a plane ticket

Second, we are attracted to a Second, we are attracted to a

> [principle of uniformity](@principle-of-uniformity): > [principle of uniformity](@):

> if a chunk of text has a certain > if a chunk of text has a certain

> meaning, it will continue to have the same meaning when put into a > meaning, it will continue to have the same meaning when put into a

> container block (such as a list item or blockquote). > container block (such as a list item or blockquote).

(Indeed, the spec for [list items] and [block quotes] presupposes (Indeed, the spec for [list items] and [block quotes] presupposes

this principle.) This principle implies that if this principle.) This principle implies that if

* I need to buy * I need to buy

- new shoes - new shoes

- a coat - a coat

skipping to change at line 4366 skipping to change at line 4466

2. Require blank lines in none of these places. 2. Require blank lines in none of these places.

[reStructuredText](http://docutils.sourceforge.net/rst.html) takes [reStructuredText](http://docutils.sourceforge.net/rst.html) takes

the first approach, for which there is much to be said. But the second the first approach, for which there is much to be said. But the second

seems more consistent with established practice with Markdown. seems more consistent with established practice with Markdown.

There can be blank lines between items, but two blank lines end There can be blank lines between items, but two blank lines end

a list: a list:

. ```````````````````````````````` example

- foo - foo

- bar - bar

- baz - baz

. .

foo

bar

baz baz

. ````````````````````````````````

As illustrated above in the section on [list items], As illustrated above in the section on [list items],

two blank lines between blocks *within* a list item will also end a two blank lines between blocks *within* a list item will also end a

list: list:

. ```````````````````````````````` example

- foo - foo

bar bar

- baz - baz

. .

foo foo

bar

baz baz

. ````````````````````````````````

Indeed, two blank lines will end *all* containing lists: Indeed, two blank lines will end *all* containing lists:

. ```````````````````````````````` example

- foo - foo

- bar - bar

- baz - baz

bim bim

. .

foo foo

bar bar

baz baz

bim

bim

. ````````````````````````````````

Thus, two blank lines can be used to separate consecutive lists of 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 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 that would otherwise be parsed as a subparagraph of the final list

item: item:

. ```````````````````````````````` example

- foo - foo

- bar - bar

- baz - baz

- bim - bim

. .

foo foo

bar bar

baz baz

bim bim

. ````````````````````````````````

. ```````````````````````````````` example

- foo - foo

notcode notcode

- foo - foo

code code

. .

foo

notcode

foo

code

code

. ````````````````````````````````

List items need not be indented to the same level. The following List items need not be indented to the same level. The following

list items will be treated as items at the same list level, list items will be treated as items at the same list level,

since none is indented enough to belong to the previous list since none is indented enough to belong to the previous list

item: item:

. ```````````````````````````````` example

- a - a

- b - b

- c - c

- d - d

- e - e

- f - f

- g - g

- h - h

- i - i

. .

skipping to change at line 4500 skipping to change at line 4600

a a

b b

c c

d d

e e

f f

g g

h h

i i

. ````````````````````````````````

. ```````````````````````````````` example

1. a 1. a

2. b 2. b

3. c 3. c

. .

. ````````````````````````````````

This is a loose list, because there is a blank line between This is a loose list, because there is a blank line between

two of the list items: two of the list items:

. ```````````````````````````````` example

- a - a

- b - b

- c - c

. .

. ````````````````````````````````

So is this, with a empty second item: So is this, with a empty second item:

. ```````````````````````````````` example

* a * a

* *

* c * c

. .

. ````````````````````````````````

These are loose lists, even though there is no space between the items, These are loose lists, even though there is no space between the items,

because one of the items directly contains two block-level elements because one of the items directly contains two block-level elements

with a blank line between them: with a blank line between them:

. ```````````````````````````````` example

- a - a

- b - b

c c

- d - d

. .

. ````````````````````````````````

. ```````````````````````````````` example

- a - a

- b - b

[ref]: /url [ref]: /url

- d - d

. .

. ````````````````````````````````

This is a tight list, because the blank lines are in a code block: This is a tight list, because the blank lines are in a code block:

. ```````````````````````````````` example

- a - a

- ``` - ```

b b

``` ```

- c - c

. .

a a

c c

. ````````````````````````````````

This is a tight list, because the blank line is between two This is a tight list, because the blank line is between two

paragraphs of a sublist. So the sublist is loose while paragraphs of a sublist. So the sublist is loose while

the outer list is tight: the outer list is tight:

. ```````````````````````````````` example

- a - a

- b - b

c c

- d - d

. .

a a

d d

. ````````````````````````````````

This is a tight list, because the blank line is inside the This is a tight list, because the blank line is inside the

block quote: block quote:

. ```````````````````````````````` example

* a * a

> b > b

> >

* c * c

. .

a a

c c

. ````````````````````````````````

This list is tight, because the consecutive block elements This list is tight, because the consecutive block elements

are not separated by blank lines: are not separated by blank lines:

. ```````````````````````````````` example

- a - a

> b > b

``` ```

c c

``` ```

- d - d

. .

a a

d d

. ````````````````````````````````

A single-paragraph list is tight: A single-paragraph list is tight:

. ```````````````````````````````` example

- a - a

. .

a a

. ````````````````````````````````

. ```````````````````````````````` example

- a - a

- b - b

. .

a a

b b

. ````````````````````````````````

This list is loose, because of the blank line between the This list is loose, because of the blank line between the

two block elements in the list item: two block elements in the list item:

. ```````````````````````````````` example

1. ``` 1. ```

foo foo

``` ```

bar bar

. .

foo

foo

bar

. ````````````````````````````````

Here the outer list is loose, the inner list tight: Here the outer list is loose, the inner list tight:

. ```````````````````````````````` example

* foo * foo

* bar * bar

baz baz

. .

foo

bar bar

baz

. ````````````````````````````````

. ```````````````````````````````` example

- a - a

- b - b

- c - c

- d - d

- e - e

- f - f

. .

skipping to change at line 4781 skipping to change at line 4881

e e

f f

. ````````````````````````````````

# Inlines # Inlines

Inlines are parsed sequentially from the beginning of the character Inlines are parsed sequentially from the beginning of the character

stream to the end (left to right, in left-to-right languages). stream to the end (left to right, in left-to-right languages).

Thus, for example, in Thus, for example, in

. ```````````````````````````````` example

`hi`lo` `hi`lo`

. .

hilo`

. ````````````````````````````````

`hi` is parsed as code, leaving the backtick at the end as a literal `hi` is parsed as code, leaving the backtick at the end as a literal

backtick. backtick.

## Backslash escapes ## Backslash escapes

Any ASCII punctuation character may be backslash-escaped: Any ASCII punctuation character may be backslash-escaped:

. ```````````````````````````````` example

\!\"\#\$\%\&\'\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~ \!\"\#\$\%\&\'\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~

. .

!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

. ````````````````````````````````

Backslashes before other characters are treated as literal Backslashes before other characters are treated as literal

backslashes: backslashes:

. ```````````````````````````````` example

\→\A\a\ \3\φ\« \→\A\a\ \3\φ\«

. .

\→\A\a\ \3\φ\«

. ````````````````````````````````

Escaped characters are treated as regular characters and do Escaped characters are treated as regular characters and do

not have their usual Markdown meanings: not have their usual Markdown meanings:

. ```````````````````````````````` example

\*not emphasized* \*not emphasized*

\
not a tag \
not a tag

\[not a link](/foo) \[not a link](/foo)

\`not code` \`not code`

1\. not a list 1\. not a list

\* not a list \* not a list

\# not a heading \# not a heading

\[foo]: /url "not a reference" \[foo]: /url "not a reference"

. .

*not emphasized*

<br/> not a tag <br/> not a tag

[not a link](/foo) [not a link](/foo)

`not code` `not code`

1. not a list 1. not a list

* not a list * not a list

# not a heading # not a heading

[foo]: /url "not a reference"

. ````````````````````````````````

If a backslash is itself escaped, the following character is not: If a backslash is itself escaped, the following character is not:

. ```````````````````````````````` example

\\*emphasis* \\*emphasis*

. .

\emphasis

. ````````````````````````````````

A backslash at the end of the line is a [hard line break]: A backslash at the end of the line is a [hard line break]:

. ```````````````````````````````` example

foo\ foo\

bar bar

. .

foo

bar

. ````````````````````````````````

Backslash escapes do not work in code blocks, code spans, autolinks, or Backslash escapes do not work in code blocks, code spans, autolinks, or

raw HTML: raw HTML:

. ```````````````````````````````` example

`` \[\` `` `` \[\` ``

. .

\[\`

. ````````````````````````````````

. ```````````````````````````````` example

\[\] \[\]

. .

\[\]

\[\]

. ````````````````````````````````

. ```````````````````````````````` example

~~~ ~~~

\[\] \[\]

~~~ ~~~

. .

\[\]

\[\]

. ````````````````````````````````

. ```````````````````````````````` example

. .

. ````````````````````````````````

. ```````````````````````````````` example

. .

. ````````````````````````````````

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 string]s in [fenced code block]s: link references, and [info strings] in [fenced code blocks]:

. ```````````````````````````````` example

[foo](/bar\* "ti\*tle") [foo](/bar\* "ti\*tle")

. .

. ````````````````````````````````

. ```````````````````````````````` example

[foo] [foo]

[foo]: /bar\* "ti\*tle" [foo]: /bar\* "ti\*tle"

. .

. ````````````````````````````````

. ```````````````````````````````` example

``` foo\+bar ``` foo\+bar

foo foo

``` ```

. .

foo

foo

. ````````````````````````````````

## Entity and numeric character references ## Entity and numeric character references

All valid HTML entity references and numeric character All valid HTML entity references and numeric character

references, except those occuring in code blocks, code spans, references, except those occuring in code blocks and code spans,

and raw HTML, are recognized as such and treated as equivalent to the are recognized as such and treated as equivalent to the

corresponding Unicode characters. Conforming CommonMark parsers corresponding Unicode characters. Conforming CommonMark parsers

need not store information about whether a particular character need not store information about whether a particular character

was represented in the source using a Unicode character or was represented in the source using a Unicode character or

an entity reference. an entity reference.

[Entity references](@entity-references) consist of `&` + any of the valid [Entity references](@) consist of `&` + any of the valid

HTML5 entity names + `;`. The HTML5 entity names + `;`. The

document document

is used as an authoritative source for the valid entity is used as an authoritative source for the valid entity

references and their corresponding code points. references and their corresponding code points.

. ```````````````````````````````` example

& © Æ Ď & © Æ Ď

¾ ℋ ⅆ ¾ ℋ ⅆ

∲ ≧̸ ∲ ≧̸

. .

& © Æ Ď

¾ ℋ ⅆ ¾ ℋ ⅆ

∲ ≧̸

. ````````````````````````````````

[Decimal numeric character [Decimal numeric character

references](@decimal-numeric-character-references) references](@)

consist of `&#` + a string of 1--8 arabic digits + `;`. A consist of `&#` + a string of 1--8 arabic digits + `;`. A

numeric character reference is parsed as the corresponding numeric character reference is parsed as the corresponding

Unicode character. Invalid Unicode code points will be replaced by Unicode character. Invalid Unicode code points will be replaced by

the "unknown code point" character (`U+FFFD`). For security reasons, the REPLACEMENT CHARACTER (`U+FFFD`). For security reasons,

the code point `U+0000` will also be replaced by `U+FFFD`. the code point `U+0000` will also be replaced by `U+FFFD`.

. ```````````````````````````````` example

# Ӓ Ϡ � � # Ӓ Ϡ � �

. .

# Ӓ Ϡ � �

. ````````````````````````````````

[Hexadecimal numeric character [Hexadecimal numeric character

references](@hexadecimal-numeric-character-references) consist of `&#` + references](@) consist of `&#` +

either `X` or `x` + a string of 1-8 hexadecimal digits + `;`. either `X` or `x` + a string of 1-8 hexadecimal digits + `;`.

They too are parsed as the corresponding Unicode character (this They too are parsed as the corresponding Unicode character (this

time specified with a hexadecimal numeral instead of decimal). time specified with a hexadecimal numeral instead of decimal).

. ```````````````````````````````` example

" ആ ಫ " ആ ಫ

. .

" ആ ಫ

. ````````````````````````````````

Here are some nonentities: Here are some nonentities:

. ```````````````````````````````` example

&x; &#; &#x; &x; &#; &#x;

&ThisIsWayTooLongToBeAnEntityIsntIt; &hi?; &ThisIsNotDefined; &hi?;

. .

&nbsp &x; &#; &#x;

&ThisIsWayTooLongToBeAnEntityIsntIt; &hi?;

&ThisIsNotDefined; &hi?;

. ````````````````````````````````

Although HTML5 does accept some entity references Although HTML5 does accept some entity references

without a trailing semicolon (such as `©`), these are not without a trailing semicolon (such as `©`), these are not

recognized here, because it makes the grammar too ambiguous: recognized here, because it makes the grammar too ambiguous:

. ```````````````````````````````` example

. .

&copy

. ````````````````````````````````

Strings that are not on the list of HTML5 named entities are not Strings that are not on the list of HTML5 named entities are not

recognized as entity references either: recognized as entity references either:

. ```````````````````````````````` example

&MadeUpEntity; &MadeUpEntity;

. .

&MadeUpEntity;

. ````````````````````````````````

Entity and numeric character references are recognized in any Entity and numeric character references are recognized in any

context besides code spans or code blocks or raw HTML, including context besides code spans or code blocks, including

URLs, [link title]s, and [fenced code block][] [info string]s: URLs, [link titles], and [fenced code block][] [info strings]:

. ```````````````````````````````` example

. .

. ````````````````````````````````

. ```````````````````````````````` example

[foo](/föö "föö") [foo](/föö "föö")

. .

. ````````````````````````````````

. ```````````````````````````````` example

[foo] [foo]

[foo]: /föö "föö" [foo]: /föö "föö"

. .

. ````````````````````````````````

. ```````````````````````````````` example

``` föö ``` föö

foo foo

``` ```

. .

foo

foo

. ````````````````````````````````

Entity and numeric character references are treated as literal Entity and numeric character references are treated as literal

text in code spans and code blocks, and in raw HTML: text in code spans and code blocks:

. ```````````````````````````````` example

`föö` `föö`

. .

föö

. ````````````````````````````````

. ```````````````````````````````` example

föfö föfö

. .

f&ouml;f&ouml;

f&ouml;f&ouml;

. ````````````````````````````````

## Code spans ## Code spans

A [backtick string](@backtick-string) A [backtick string](@)

is a string of one or more backtick characters (`` ` ``) that is neither is a string of one or more backtick characters (`` ` ``) that is neither

preceded nor followed by a backtick. preceded nor followed by a backtick.

A [code span](@code-span) begins with a backtick string and ends with A [code span](@) begins with a backtick string and ends with

a backtick string of equal length. The contents of the code span are a backtick string of equal length. The contents of the code span are

the characters between the two backtick strings, with leading and the characters between the two backtick strings, with leading and

trailing spaces and [line ending]s removed, and trailing spaces and [line endings] removed, and

[whitespace] collapsed to single spaces. [whitespace] collapsed to single spaces.

This is a simple code span: This is a simple code span:

. ```````````````````````````````` example

`foo` `foo`

. .

foo

. ````````````````````````````````

Here two backticks are used, because the code contains a backtick. Here two backticks are used, because the code contains a backtick.

This example also illustrates stripping of leading and trailing spaces: This example also illustrates stripping of leading and trailing spaces:

. ```````````````````````````````` example

`` foo ` bar `` `` foo ` bar ``

. .

foo ` bar

. ````````````````````````````````

This example shows the motivation for stripping leading and trailing This example shows the motivation for stripping leading and trailing

spaces: spaces:

. ```````````````````````````````` example

` `` ` ` `` `

. .

. ````````````````````````````````

[Line ending]s are treated like spaces: [Line endings] are treated like spaces:

. ```````````````````````````````` example

`` ``

foo foo

`` ``

. .

foo

. ````````````````````````````````

Interior spaces and [line ending]s are collapsed into Interior spaces and [line endings] are collapsed into

single spaces, just as they would be by a browser: single spaces, just as they would be by a browser:

. ```````````````````````````````` example

`foo bar `foo bar

baz` baz`

. .

foo bar baz

. ````````````````````````````````

Q: Why not just leave the spaces, since browsers will collapse them Q: Why not just leave the spaces, since browsers will collapse them

anyway? A: Because we might be targeting a non-HTML format, and we anyway? A: Because we might be targeting a non-HTML format, and we

shouldn't rely on HTML-specific rendering assumptions. shouldn't rely on HTML-specific rendering assumptions.

(Existing implementations differ in their treatment of internal (Existing implementations differ in their treatment of internal

spaces and [line ending]s. Some, including `Markdown.pl` and spaces and [line endings]. Some, including `Markdown.pl` and

`showdown`, convert an internal [line ending] into a `showdown`, convert an internal [line ending] into a

`
` tag. But this makes things difficult for those who like to `
` tag. But this makes things difficult for those who like to

hard-wrap their paragraphs, since a line break in the midst of a code hard-wrap their paragraphs, since a line break in the midst of a code

span will cause an unintended line break in the output. Others just span will cause an unintended line break in the output. Others just

leave internal spaces as they are, which is fine if only HTML is being leave internal spaces as they are, which is fine if only HTML is being

targeted.) targeted.)

. ```````````````````````````````` example

`foo `` bar` `foo `` bar`

. .

foo `` bar

. ````````````````````````````````

Note that backslash escapes do not work in code spans. All backslashes Note that backslash escapes do not work in code spans. All backslashes

are treated literally: are treated literally:

. ```````````````````````````````` example

`foo\`bar` `foo\`bar`

. .

foo\bar`

. ````````````````````````````````

Backslash escapes are never needed, because one can always choose a Backslash escapes are never needed, because one can always choose a

string of *n* backtick characters as delimiters, where the code does string of *n* backtick characters as delimiters, where the code does

not contain any strings of exactly *n* backtick characters. not contain any strings of exactly *n* backtick characters.

Code span backticks have higher precedence than any other inline Code span backticks have higher precedence than any other inline

constructs except HTML tags and autolinks. Thus, for example, this is constructs except HTML tags and autolinks. Thus, for example, this is

not parsed as emphasized text, since the second `*` is part of a code not parsed as emphasized text, since the second `*` is part of a code

span: span:

. ```````````````````````````````` example

*foo`*` *foo`*`

. .

*foo*

. ````````````````````````````````

And this is not parsed as a link: And this is not parsed as a link:

. ```````````````````````````````` example

[not a `link](/foo`) [not a `link](/foo`)

. .

[not a link](/foo)

. ````````````````````````````````

Code spans, HTML tags, and autolinks have the same precedence. Code spans, HTML tags, and autolinks have the same precedence.

Thus, this is code: Thus, this is code:

. ```````````````````````````````` example

`` ``

. .

<a href="">`

. ````````````````````````````````

But this is an HTML tag: But this is an HTML tag:

. ```````````````````````````````` example

. .

. ````````````````````````````````

And this is code: And this is code:

. ```````````````````````````````` example

`` ``

. .

<http://foo.bar.baz>`

. ````````````````````````````````

But this is an autolink: But this is an autolink:

. ```````````````````````````````` example

` `

. .

http://foo.bar.`baz`

. ````````````````````````````````

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

```foo`` ```foo``

. .

```foo``

. ````````````````````````````````

. ```````````````````````````````` example

`foo `foo

. .

`foo

. ````````````````````````````````

## 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](http://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

> `` tag; double `*`'s or `_`'s will be wrapped with an HTML `` > `` tag; double `*`'s or `_`'s will be wrapped with an HTML ``

> tag. > tag.

skipping to change at line 5260 skipping to change at line 5354

spans, but users often do not.) spans, but users often do not.)

``` markdown ``` markdown

internal emphasis: foo*bar*baz internal emphasis: foo*bar*baz

no emphasis: foo_bar_baz no emphasis: foo_bar_baz

``` ```

The rules given below capture all of these patterns, while allowing The rules given below capture all of these patterns, while allowing

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](@) 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](@) 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].

For purposes of this definition, the beginning and the end of For purposes of this definition, the beginning and the end of

the line count as Unicode whitespace. the line count as Unicode whitespace.

A [right-flanking delimiter run](@right-flanking-delimiter-run) is A [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].

For purposes of this definition, the beginning and the end of For purposes of this definition, the beginning and the end of

the line count as Unicode whitespace. the line count as Unicode whitespace.

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:

skipping to change at line 5323 skipping to change at line 5417

(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](http://www.vfmd.org/vfmd-spec/specification/#procedure-for-identifying-em phasis-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](@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

it is part of a [left-flanking delimiter run] it is part of a [left-flanking delimiter run]

and either (a) not part of a [right-flanking delimiter run] and either (a) not part of a [right-flanking delimiter run]

or (b) part of a [right-flanking delimiter run] or (b) part of a [right-flanking delimiter run]

preceded by punctuation. preceded by punctuation.

3. A single `*` character [can close emphasis](@can-close-emphasis) 3. A single `*` character [can close emphasis](@)

iff it is part of a [right-flanking delimiter run]. iff it is part of a [right-flanking delimiter run].

4. A single `_` character [can close emphasis] iff 4. A single `_` character [can close emphasis] iff

it is part of a [right-flanking delimiter run] it is part of a [right-flanking delimiter run]

and either (a) not part of a [left-flanking delimiter run] and either (a) not part of a [left-flanking delimiter run]

or (b) part of a [left-flanking delimiter run] or (b) part of a [left-flanking delimiter run]

followed by punctuation. followed by punctuation.

5. A double `**` [can open strong emphasis](@can-open-strong-emphasis) 5. A double `**` [can open strong emphasis](@)

iff it is part of a [left-flanking delimiter run]. iff it is part of a [left-flanking delimiter run].

6. A double `__` [can open strong emphasis] iff 6. A double `__` [can open strong emphasis] iff

it is part of a [left-flanking delimiter run] it is part of a [left-flanking delimiter run]

and either (a) not part of a [right-flanking delimiter run] and either (a) not part of a [right-flanking delimiter run]

or (b) part of a [right-flanking delimiter run] or (b) part of a [right-flanking delimiter run]

preceded by punctuation. preceded by punctuation.

7. A double `**` [can close strong emphasis](@can-close-strong-emphasis) 7. A double `**` [can close strong emphasis](@)

iff it is part of a [right-flanking delimiter run]. iff it is part of a [right-flanking delimiter run].

8. A double `__` [can close strong emphasis] 8. A double `__` [can close strong emphasis]

it is part of a [right-flanking delimiter run] it is part of a [right-flanking delimiter run]

and either (a) not part of a [left-flanking delimiter run] and either (a) not part of a [left-flanking delimiter run]

or (b) part of a [left-flanking delimiter run] or (b) part of a [left-flanking delimiter run]

followed by punctuation. followed by punctuation.

9. Emphasis begins with a delimiter that [can open emphasis] and ends 9. Emphasis begins with a delimiter that [can open emphasis] and ends

with a delimiter that [can close emphasis], and that uses the same with a delimiter that [can close emphasis], and that uses the same

skipping to change at line 5417 skipping to change at line 5511

than emphasis. So, when there is a choice between an interpretation than emphasis. So, when there is a choice between an interpretation

that contains one of these elements and one that does not, the that contains one of these elements and one that does not, the

former always wins. Thus, for example, `*[foo*](bar)` is former always wins. Thus, for example, `*[foo*](bar)` is

parsed as `*foo*` rather than as parsed as `*foo*` rather than as

`[foo](bar)`. `[foo](bar)`.

These rules can be illustrated through a series of examples. These rules can be illustrated through a series of examples.

Rule 1: Rule 1:

. ```````````````````````````````` example

*foo bar* *foo bar*

. .

foo bar

. ````````````````````````````````

This is not emphasis, because the opening `*` is followed by This is not emphasis, because the opening `*` is followed by

whitespace, and hence not part of a [left-flanking delimiter run]: whitespace, and hence not part of a [left-flanking delimiter run]:

. ```````````````````````````````` example

a * foo bar* a * foo bar*

. .

a * foo bar*

. ````````````````````````````````

This is not emphasis, because the opening `*` is preceded This is not emphasis, because the opening `*` is preceded

by an alphanumeric and followed by punctuation, and hence by an alphanumeric and followed by punctuation, and hence

not part of a [left-flanking delimiter run]: not part of a [left-flanking delimiter run]:

. ```````````````````````````````` example

a*"foo"* a*"foo"*

. .

a*"foo"*

. ````````````````````````````````

Unicode nonbreaking spaces count as whitespace, too: Unicode nonbreaking spaces count as whitespace, too:

. ```````````````````````````````` example

* a * * a *

. .

* a *

. ````````````````````````````````

Intraword emphasis with `*` is permitted: Intraword emphasis with `*` is permitted:

. ```````````````````````````````` example

foo*bar* foo*bar*

. .

foobar

. ````````````````````````````````

. ```````````````````````````````` example

5*6*78 5*6*78

. .

5678

. ````````````````````````````````

Rule 2: Rule 2:

. ```````````````````````````````` example

_foo bar_ _foo bar_

. .

foo bar

. ````````````````````````````````

This is not emphasis, because the opening `_` is followed by This is not emphasis, because the opening `_` is followed by

whitespace: whitespace:

. ```````````````````````````````` example

_ foo bar_ _ foo bar_

. .

_ foo bar_

. ````````````````````````````````

This is not emphasis, because the opening `_` is preceded This is not emphasis, because the opening `_` is preceded

by an alphanumeric and followed by punctuation: by an alphanumeric and followed by punctuation:

. ```````````````````````````````` example

a_"foo"_ a_"foo"_

. .

a_"foo"_

. ````````````````````````````````

Emphasis with `_` is not allowed inside words: Emphasis with `_` is not allowed inside words:

. ```````````````````````````````` example

foo_bar_ foo_bar_

. .

foo_bar_

. ````````````````````````````````

. ```````````````````````````````` example

5_6_78 5_6_78

. .

5_6_78

. ````````````````````````````````

. ```````````````````````````````` example

пристаням_стремятся_ пристаням_стремятся_

. .

пристаням_стремятся_

. ````````````````````````````````

Here `_` does not generate emphasis, because the first delimiter run Here `_` does not generate emphasis, because the first delimiter run

is right-flanking and the second left-flanking: is right-flanking and the second left-flanking:

. ```````````````````````````````` example

aa_"bb"_cc aa_"bb"_cc

. .

aa_"bb"_cc

. ````````````````````````````````

This is emphasis, even though the opening delimiter is This is emphasis, even though the opening delimiter is

both left- and right-flanking, because it is preceded by both left- and right-flanking, because it is preceded by

punctuation: punctuation:

. ```````````````````````````````` example

foo-_(bar)_ foo-_(bar)_

. .

foo-(bar)

. ````````````````````````````````

Rule 3: Rule 3:

This is not emphasis, because the closing delimiter does This is not emphasis, because the closing delimiter does

not match the opening delimiter: not match the opening delimiter:

. ```````````````````````````````` example

_foo* _foo*

. .

_foo*

. ````````````````````````````````

This is not emphasis, because the closing `*` is preceded by This is not emphasis, because the closing `*` is preceded by

whitespace: whitespace:

. ```````````````````````````````` example

*foo bar * *foo bar *

. .

*foo bar *

. ````````````````````````````````

A newline also counts as whitespace: A newline also counts as whitespace:

. ```````````````````````````````` example

*foo bar *foo bar

* *

. .

*foo bar

. ````````````````````````````````

This is not emphasis, because the second `*` is This is not emphasis, because the second `*` is

preceded by punctuation and followed by an alphanumeric preceded by punctuation and followed by an alphanumeric

(hence it is not part of a [right-flanking delimiter run]: (hence it is not part of a [right-flanking delimiter run]:

. ```````````````````````````````` example

*(*foo) *(*foo)

. .

*(*foo)

. ````````````````````````````````

The point of this restriction is more easily appreciated The point of this restriction is more easily appreciated

with this example: with this example:

. ```````````````````````````````` example

*(*foo*)* *(*foo*)*

. .

(foo)

. ````````````````````````````````

Intraword emphasis with `*` is allowed: Intraword emphasis with `*` is allowed:

. ```````````````````````````````` example

*foo*bar *foo*bar

. .

foobar

. ````````````````````````````````

Rule 4: Rule 4:

This is not emphasis, because the closing `_` is preceded by This is not emphasis, because the closing `_` is preceded by

whitespace: whitespace:

. ```````````````````````````````` example

_foo bar _ _foo bar _

. .

_foo bar _

. ````````````````````````````````

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:

. ```````````````````````````````` example

_(_foo) _(_foo)

. .

_(_foo)

. ````````````````````````````````

This is emphasis within emphasis: This is emphasis within emphasis:

. ```````````````````````````````` example

_(_foo_)_ _(_foo_)_

. .

(foo)

. ````````````````````````````````

Intraword emphasis is disallowed for `_`: Intraword emphasis is disallowed for `_`:

. ```````````````````````````````` example

_foo_bar _foo_bar

. .

_foo_bar

. ````````````````````````````````

. ```````````````````````````````` example

_пристаням_стремятся _пристаням_стремятся

. .

_пристаням_стремятся

. ````````````````````````````````

. ```````````````````````````````` example

_foo_bar_baz_ _foo_bar_baz_

. .

foo_bar_baz

. ````````````````````````````````

This is emphasis, even though the closing delimiter is This is emphasis, even though the closing delimiter is

both left- and right-flanking, because it is followed by both left- and right-flanking, because it is followed by

punctuation: punctuation:

. ```````````````````````````````` example

_(bar)_. _(bar)_.

. .

(bar).

. ````````````````````````````````

Rule 5: Rule 5:

. ```````````````````````````````` example

**foo bar** **foo bar**

. .

foo bar

. ````````````````````````````````

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:

. ```````````````````````````````` example

** foo bar** ** foo bar**

. .

** foo bar**

. ````````````````````````````````

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, and hence by an alphanumeric and followed by punctuation, and hence

not part of a [left-flanking delimiter run]: not part of a [left-flanking delimiter run]:

. ```````````````````````````````` example

a**"foo"** a**"foo"**

. .

a**"foo"**

. ````````````````````````````````

Intraword strong emphasis with `**` is permitted: Intraword strong emphasis with `**` is permitted:

. ```````````````````````````````` example

foo**bar** foo**bar**

. .

foobar

. ````````````````````````````````

Rule 6: Rule 6:

. ```````````````````````````````` example

__foo bar__ __foo bar__

. .

foo bar

. ````````````````````````````````

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:

. ```````````````````````````````` example

__ foo bar__ __ foo bar__

. .

__ foo bar__

. ````````````````````````````````

A newline counts as whitespace: A newline counts as whitespace:

. ```````````````````````````````` example

__ __

foo bar__ foo bar__

. .

foo bar__

. ````````````````````````````````

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:

. ```````````````````````````````` example

a__"foo"__ a__"foo"__

. .

a__"foo"__

. ````````````````````````````````

Intraword strong emphasis is forbidden with `__`: Intraword strong emphasis is forbidden with `__`:

. ```````````````````````````````` example

foo__bar__ foo__bar__

. .

foo__bar__

. ````````````````````````````````

. ```````````````````````````````` example

5__6__78 5__6__78

. .

5__6__78

. ````````````````````````````````

. ```````````````````````````````` example

пристаням__стремятся__ пристаням__стремятся__

. .

пристаням__стремятся__

. ````````````````````````````````

. ```````````````````````````````` example

__foo, __bar__, baz__ __foo, __bar__, baz__

. .

foo, bar, baz

. ````````````````````````````````

This is strong emphasis, even though the opening delimiter is This is strong emphasis, even though the opening delimiter is

both left- and right-flanking, because it is preceded by both left- and right-flanking, because it is preceded by

punctuation: punctuation:

. ```````````````````````````````` example

foo-__(bar)__ foo-__(bar)__

. .

foo-(bar)

. ````````````````````````````````

Rule 7: Rule 7:

This is not strong emphasis, because the closing delimiter is preceded This is not strong emphasis, because the closing delimiter is preceded

by whitespace: by whitespace:

. ```````````````````````````````` example

**foo bar ** **foo bar **

. .

**foo bar **

. ````````````````````````````````

(Nor can it be interpreted as an emphasized `*foo bar *`, because of (Nor can it be interpreted as an emphasized `*foo bar *`, because of

Rule 11.) Rule 11.)

This is not strong emphasis, because the second `**` is This is not strong emphasis, because the second `**` is

preceded by punctuation and followed by an alphanumeric: preceded by punctuation and followed by an alphanumeric:

. ```````````````````````````````` example

**(**foo) **(**foo)

. .

**(**foo)

. ````````````````````````````````

The point of this restriction is more easily appreciated The point of this restriction is more easily appreciated

with these examples: with these examples:

. ```````````````````````````````` example

*(**foo**)* *(**foo**)*

. .

(foo)

. ````````````````````````````````

. ```````````````````````````````` example

**Gomphocarpus (*Gomphocarpus physocarpus*, syn. **Gomphocarpus (*Gomphocarpus physocarpus*, syn.

*Asclepias physocarpa*)** *Asclepias physocarpa*)**

. .

Gomphocarpus (Gomphocarpus physocarpus, syn.

Asclepias physocarpa)

. ````````````````````````````````

. ```````````````````````````````` example

**foo "*bar*" foo** **foo "*bar*" foo**

. .

foo "bar" foo

. ````````````````````````````````

Intraword emphasis: Intraword emphasis:

. ```````````````````````````````` example

**foo**bar **foo**bar

. .

foobar

. ````````````````````````````````

Rule 8: Rule 8:

This is not strong emphasis, because the closing delimiter is This is not strong emphasis, because the closing delimiter is

preceded by whitespace: preceded by whitespace:

. ```````````````````````````````` example

__foo bar __ __foo bar __

. .

__foo bar __

. ````````````````````````````````

This is not strong emphasis, because the second `__` is This is not strong emphasis, because the second `__` is

preceded by punctuation and followed by an alphanumeric: preceded by punctuation and followed by an alphanumeric:

. ```````````````````````````````` example

__(__foo) __(__foo)

. .

__(__foo)

. ````````````````````````````````

The point of this restriction is more easily appreciated The point of this restriction is more easily appreciated

with this example: with this example:

. ```````````````````````````````` example

_(__foo__)_ _(__foo__)_

. .

(foo)

. ````````````````````````````````

Intraword strong emphasis is forbidden with `__`: Intraword strong emphasis is forbidden with `__`:

. ```````````````````````````````` example

__foo__bar __foo__bar

. .

__foo__bar

. ````````````````````````````````

. ```````````````````````````````` example

__пристаням__стремятся __пристаням__стремятся

. .

__пристаням__стремятся

. ````````````````````````````````

. ```````````````````````````````` example

__foo__bar__baz__ __foo__bar__baz__

. .

foo__bar__baz

. ````````````````````````````````

This is strong emphasis, even though the closing delimiter is This is strong emphasis, even though the closing delimiter is

both left- and right-flanking, because it is followed by both left- and right-flanking, because it is followed by

punctuation: punctuation:

. ```````````````````````````````` example

__(bar)__. __(bar)__.

. .

(bar).

. ````````````````````````````````

Rule 9: Rule 9:

Any nonempty sequence of inline elements can be the contents of an Any nonempty sequence of inline elements can be the contents of an

emphasized span. emphasized span.

. ```````````````````````````````` example

*foo [bar](/url)* *foo [bar](/url)*

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

*foo *foo

bar* bar*

. .

foo

bar

. ````````````````````````````````

In particular, emphasis and strong emphasis can be nested In particular, emphasis and strong emphasis can be nested

inside emphasis: inside emphasis:

. ```````````````````````````````` example

_foo __bar__ baz_ _foo __bar__ baz_

. .

foo bar baz

. ````````````````````````````````

. ```````````````````````````````` example

_foo _bar_ baz_ _foo _bar_ baz_

. .

foo bar baz

. ````````````````````````````````

. ```````````````````````````````` example

__foo_ bar_ __foo_ bar_

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

*foo *bar** *foo *bar**

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

*foo **bar** baz* *foo **bar** baz*

. .

foo bar baz

. ````````````````````````````````

But note: But note:

. ```````````````````````````````` example

*foo**bar**baz* *foo**bar**baz*

. .

foobarbaz

. ````````````````````````````````

The difference is that in the preceding case, the internal delimiters The difference is that in the preceding case, the internal delimiters

[can close emphasis], while in the cases with spaces, they cannot. [can close emphasis], while in the cases with spaces, they cannot.

. ```````````````````````````````` example

***foo** bar* ***foo** bar*

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

*foo **bar*** *foo **bar***

. .

foo bar

. ````````````````````````````````

Note, however, that in the following case we get no strong Note, however, that in the following case we get no strong

emphasis, because the opening delimiter is closed by the first emphasis, because the opening delimiter is closed by the first

`*` before `bar`: `*` before `bar`:

. ```````````````````````````````` example

*foo**bar*** *foo**bar***

. .

foobar**

. ````````````````````````````````

Indefinite levels of nesting are possible: Indefinite levels of nesting are possible:

. ```````````````````````````````` example

*foo **bar *baz* bim** bop* *foo **bar *baz* bim** bop*

. .

foo bar baz bim bop

. ````````````````````````````````

. ```````````````````````````````` example

*foo [*bar*](/url)* *foo [*bar*](/url)*

. .

foo bar

. ````````````````````````````````

There can be no empty emphasis or strong emphasis: There can be no empty emphasis or strong emphasis:

. ```````````````````````````````` example

** is not an empty emphasis ** is not an empty emphasis

. .

** is not an empty emphasis

. ````````````````````````````````

. ```````````````````````````````` example

**** is not an empty strong emphasis **** is not an empty strong emphasis

. .

**** is not an empty strong emphasis

. ````````````````````````````````

Rule 10: Rule 10:

Any nonempty sequence of inline elements can be the contents of an Any nonempty sequence of inline elements can be the contents of an

strongly emphasized span. strongly emphasized span.

. ```````````````````````````````` example

**foo [bar](/url)** **foo [bar](/url)**

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

**foo **foo

bar** bar**

. .

foo

bar

. ````````````````````````````````

In particular, emphasis and strong emphasis can be nested In particular, emphasis and strong emphasis can be nested

inside strong emphasis: inside strong emphasis:

. ```````````````````````````````` example

__foo _bar_ baz__ __foo _bar_ baz__

. .

foo bar baz

. ````````````````````````````````

. ```````````````````````````````` example

__foo __bar__ baz__ __foo __bar__ baz__

. .

foo bar baz

. ````````````````````````````````

. ```````````````````````````````` example

____foo__ bar__ ____foo__ bar__

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

**foo **bar**** **foo **bar****

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

**foo *bar* baz** **foo *bar* baz**

. .

foo bar baz

. ````````````````````````````````

But note: But note:

. ```````````````````````````````` example

**foo*bar*baz** **foo*bar*baz**

. .

foobarbaz**

. ````````````````````````````````

The difference is that in the preceding case, the internal delimiters The difference is that in the preceding case, the internal delimiters

[can close emphasis], while in the cases with spaces, they cannot. [can close emphasis], while in the cases with spaces, they cannot.

. ```````````````````````````````` example

***foo* bar** ***foo* bar**

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

**foo *bar*** **foo *bar***

. .

foo bar

. ````````````````````````````````

Indefinite levels of nesting are possible: Indefinite levels of nesting are possible:

. ```````````````````````````````` example

**foo *bar **baz** **foo *bar **baz**

bim* bop** bim* bop**

. .

foo bar baz

bim bop

. ````````````````````````````````

. ```````````````````````````````` example

**foo [*bar*](/url)** **foo [*bar*](/url)**

. .

foo bar

. ````````````````````````````````

There can be no empty emphasis or strong emphasis: There can be no empty emphasis or strong emphasis:

. ```````````````````````````````` example

__ is not an empty emphasis __ is not an empty emphasis

. .

__ is not an empty emphasis

. ````````````````````````````````

. ```````````````````````````````` example

____ is not an empty strong emphasis ____ is not an empty strong emphasis

. .

____ is not an empty strong emphasis

. ````````````````````````````````

Rule 11: Rule 11:

. ```````````````````````````````` example

foo *** foo ***

. .

foo ***

. ````````````````````````````````

. ```````````````````````````````` example

foo *\** foo *\**

. .

foo *

. ````````````````````````````````

. ```````````````````````````````` example

foo *_* foo *_*

. .

foo _

. ````````````````````````````````

. ```````````````````````````````` example

foo ***** foo *****

. .

foo *****

. ````````````````````````````````

. ```````````````````````````````` example

foo **\*** foo **\***

. .

foo *

. ````````````````````````````````

. ```````````````````````````````` example

foo **_** foo **_**

. .

foo _

. ````````````````````````````````

Note that when delimiters do not match evenly, Rule 11 determines Note that when delimiters do not match evenly, Rule 11 determines

that the excess literal `*` characters will appear outside of the that the excess literal `*` characters will appear outside of the

emphasis, rather than inside it: emphasis, rather than inside it:

. ```````````````````````````````` example

**foo* **foo*

. .

*foo

. ````````````````````````````````

. ```````````````````````````````` example

*foo** *foo**

. .

foo*

. ````````````````````````````````

. ```````````````````````````````` example

***foo** ***foo**

. .

*foo

. ````````````````````````````````

. ```````````````````````````````` example

****foo* ****foo*

. .

***foo

. ````````````````````````````````

. ```````````````````````````````` example

**foo*** **foo***

. .

foo*

. ````````````````````````````````

. ```````````````````````````````` example

*foo**** *foo****

. .

foo***

. ````````````````````````````````

Rule 12: Rule 12:

. ```````````````````````````````` example

foo ___ foo ___

. .

foo ___

. ````````````````````````````````

. ```````````````````````````````` example

foo _\__ foo _\__

. .

foo _

. ````````````````````````````````

. ```````````````````````````````` example

foo _*_ foo _*_

. .

foo *

. ````````````````````````````````

. ```````````````````````````````` example

foo _____ foo _____

. .

foo _____

. ````````````````````````````````

. ```````````````````````````````` example

foo __\___ foo __\___

. .

foo _

. ````````````````````````````````

. ```````````````````````````````` example

foo __*__ foo __*__

. .

foo *

. ````````````````````````````````

. ```````````````````````````````` example

__foo_ __foo_

. .

_foo

. ````````````````````````````````

Note that when delimiters do not match evenly, Rule 12 determines Note that when delimiters do not match evenly, Rule 12 determines

that the excess literal `_` characters will appear outside of the that the excess literal `_` characters will appear outside of the

emphasis, rather than inside it: emphasis, rather than inside it:

. ```````````````````````````````` example

_foo__ _foo__

. .

foo_

. ````````````````````````````````

. ```````````````````````````````` example

___foo__ ___foo__

. .

_foo

. ````````````````````````````````

. ```````````````````````````````` example

____foo_ ____foo_

. .

___foo

. ````````````````````````````````

. ```````````````````````````````` example

__foo___ __foo___

. .

foo_

. ````````````````````````````````

. ```````````````````````````````` example

_foo____ _foo____

. .

foo___

. ````````````````````````````````

Rule 13 implies that if you want emphasis nested directly inside Rule 13 implies that if you want emphasis nested directly inside

emphasis, you must use different delimiters: emphasis, you must use different delimiters:

. ```````````````````````````````` example

**foo** **foo**

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

*_foo_* *_foo_*

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

__foo__ __foo__

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

_*foo*_ _*foo*_

. .

foo

. ````````````````````````````````

However, strong emphasis within strong emphasis is possible without However, strong emphasis within strong emphasis is possible without

switching delimiters: switching delimiters:

. ```````````````````````````````` example

****foo**** ****foo****

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

____foo____ ____foo____

. .

foo

. ````````````````````````````````

Rule 13 can be applied to arbitrarily long sequences of Rule 13 can be applied to arbitrarily long sequences of

delimiters: delimiters:

. ```````````````````````````````` example

******foo****** ******foo******

. .

foo

. ````````````````````````````````

Rule 14: Rule 14:

. ```````````````````````````````` example

***foo*** ***foo***

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

_____foo_____ _____foo_____

. .

foo

. ````````````````````````````````

Rule 15: Rule 15:

. ```````````````````````````````` example

*foo _bar* baz_ *foo _bar* baz_

. .

foo _bar baz_

. ````````````````````````````````

. ```````````````````````````````` example

**foo*bar** **foo*bar**

. .

foobar*

. ````````````````````````````````

. ```````````````````````````````` example

*foo __bar *baz bim__ bam* *foo __bar *baz bim__ bam*

. .

foo bar *baz bim bam

. ````````````````````````````````

Rule 16: Rule 16:

. ```````````````````````````````` example

**foo **bar baz** **foo **bar baz**

. .

**foo bar baz

. ````````````````````````````````

. ```````````````````````````````` example

*foo *bar baz* *foo *bar baz*

. .

*foo bar baz

. ````````````````````````````````

Rule 17: Rule 17:

. ```````````````````````````````` example

*[bar*](/url) *[bar*](/url)

. .

*bar*

. ````````````````````````````````

. ```````````````````````````````` example

_foo [bar_](/url) _foo [bar_](/url)

. .

_foo bar_

. ````````````````````````````````

. ```````````````````````````````` example

* *

. .

. ````````````````````````````````

. ```````````````````````````````` example

** **

. .

. ````````````````````````````````

. ```````````````````````````````` example

__ __

. .

. ````````````````````````````````

. ```````````````````````````````` example

*a `*`* *a `*`*

. .

a *

. ````````````````````````````````

. ```````````````````````````````` example

_a `_`_ _a `_`_

. .

a _

. ````````````````````````````````

. ```````````````````````````````` example

**a **a

. .

**ahttp://foo.bar/?q=**

. ````````````````````````````````

. ```````````````````````````````` example

__a __a

. .

__ahttp://foo.bar/?q=__

. ````````````````````````````````

## 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 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 link]s the destination and title are defined elsewhere in [reference links] the destination and title are defined elsewhere in

the document. the document.

A [link text](@link-text) consists of a sequence of zero or more A [link text](@) consists of a sequence of zero or more

inline elements enclosed by square brackets (`[` and `]`). The inline elements enclosed by square brackets (`[` and `]`). The

following rules apply: following rules apply:

- Links may not contain other links, at any level of nesting. If - Links may not contain other links, at any level of nesting. If

multiple otherwise valid link definitions appear nested inside each multiple otherwise valid link definitions appear nested inside each

other, the inner-most definition is used. other, the inner-most definition is used.

- Brackets are allowed in the [link text] only if (a) they - Brackets are allowed in the [link text] only if (a) they

are backslash-escaped or (b) they appear as a matched pair of brackets, are backslash-escaped or (b) they appear as a matched pair of brackets,

with an open bracket `[`, a sequence of zero or more inlines, and with an open bracket `[`, a sequence of zero or more inlines, and

a close bracket `]`. a close bracket `]`.

- Backtick [code span]s, [autolink]s, and raw [HTML tag]s bind more tightly - Backtick [code spans], [autolinks], and raw [HTML tags] bind more tightly

than the brackets in link text. Thus, for example, than the brackets in link text. Thus, for example,

`` [foo`]` `` could not be a link text, since the second `]` `` [foo`]` `` could not be a link text, since the second `]`

is part of a code span. is part of a code span.

- The brackets in link text bind more tightly than markers for - The brackets in link text bind more tightly than markers for

[emphasis and strong emphasis]. Thus, for example, `*[foo*](url)` is a link. [emphasis and strong emphasis]. Thus, for example, `*[foo*](url)` is a link.

A [link destination](@link-destination) consists of either A [link destination](@) consists of either

- a sequence of zero or more characters between an opening `<` and a - a sequence of zero or more characters between an opening `<` and a

closing `>` that contains no line breaks or unescaped `<` or `>` closing `>` that contains no spaces, line breaks, or unescaped

characters, or `<` or `>` characters, or

- a nonempty sequence of characters that does not include - a nonempty sequence of characters that does not include

ASCII space or control characters, and includes parentheses ASCII space or control characters, and includes parentheses

only if (a) they are backslash-escaped or (b) they are part of only if (a) they are backslash-escaped or (b) they are part of

a balanced pair of unescaped parentheses that is not itself a balanced pair of unescaped parentheses that is not itself

inside a balanced pair of unescaped parentheses. inside a balanced pair of unescaped parentheses.

A [link title](@link-title) consists of either A [link title](@) consists of either

- a sequence of zero or more characters between straight double-quote - a sequence of zero or more characters between straight double-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 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 Although [link titles] may span multiple lines, they may not contain

a [blank line]. a [blank line].

An [inline link](@inline-link) consists of a [link text] followed immediately An [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

above. above.

Here is a simple inline link: Here is a simple inline link:

. ```````````````````````````````` example

[link](/uri "title") [link](/uri "title")

. .

. ````````````````````````````````

The title may be omitted: The title may be omitted:

. ```````````````````````````````` example

[link](/uri) [link](/uri)

. .

. ````````````````````````````````

Both the title and the destination may be omitted: Both the title and the destination may be omitted:

. ```````````````````````````````` example

[link]() [link]()

. .

. ````````````````````````````````

. ```````````````````````````````` example

[link](<>) [link](<>)

. .

. ````````````````````````````````

If the destination contains spaces, it must be enclosed in pointy The destination cannot contain spaces or line breaks,

braces: even if enclosed in pointy brackets:

. ```````````````````````````````` example

[link](/my uri) [link](/my uri)

. .

[link](/my uri)

. ````````````````````````````````

. ```````````````````````````````` example

[link]() [link]()

. .

[link](</my uri>)

. ````````````````````````````````

The destination cannot contain line breaks, even with pointy braces:

. ```````````````````````````````` example

[link](foo [link](foo

bar) bar)

. .

[link](foo

bar)

. ````````````````````````````````

. ```````````````````````````````` example

[link]( [link](

bar>) bar>)

. .

[link](

bar>)

````````````````````````````````

Parentheses inside the link destination may be escaped:

```````````````````````````````` example

[link]($foo$)

. .

````````````````````````````````

One level of balanced parentheses is allowed without escaping: One level of balanced parentheses is allowed without escaping:

. ```````````````````````````````` example

[link]((foo)and(bar)) [link]((foo)and(bar))

. .

. ````````````````````````````````

However, if you have parentheses within parentheses, you need to escape However, if you have parentheses within parentheses, you need to escape

or use the `<...>` form: or use the `<...>` form:

. ```````````````````````````````` example

[link](foo(and(bar))) [link](foo(and(bar)))

. .

[link](foo(and(bar)))

. ````````````````````````````````

. ```````````````````````````````` example

[link](foo(and$bar$)) [link](foo(and$bar$))

. .

. ````````````````````````````````

. ```````````````````````````````` example

[link]() [link]()

. .

. ````````````````````````````````

Parentheses and other symbols can also be escaped, as usual Parentheses and other symbols can also be escaped, as usual

in Markdown: in Markdown:

. ```````````````````````````````` example

[link](foo\)\:) [link](foo\)\:)

. .

. ````````````````````````````````

A link can contain fragment identifiers and queries: A link can contain fragment identifiers and queries:

. ```````````````````````````````` example

[link](#fragment) [link](#fragment)

[link](http://example.com#fragment) [link](http://example.com#fragment)

[link](http://example.com?foo=3#frag) [link](http://example.com?foo=3#frag)

. .

. ````````````````````````````````

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

[link](foo\bar) [link](foo\bar)

. .

. ````````````````````````````````

URL-escaping should be left alone inside the destination, as all URL-escaping should be left alone inside the destination, as all

URL-escaped characters are also valid URL characters. Entity and URL-escaped characters are also valid URL characters. Entity and

numerical character references in the destination will be parsed numerical character references in the destination will be parsed

into the corresponding Unicode code points, as usual. These may into the corresponding Unicode code points, as usual. These may

be optionally URL-escaped when written as HTML, but this spec be optionally URL-escaped when written as HTML, but this spec

does not enforce any particular policy for rendering URLs in does not enforce any particular policy for rendering URLs in

HTML or other formats. Renderers may make different decisions HTML or other formats. Renderers may make different decisions

about how to escape or normalize URLs in the output. about how to escape or normalize URLs in the output.

. ```````````````````````````````` example

[link](foo%20bä) [link](foo%20bä)

. .

. ````````````````````````````````

Note that, because titles can often be parsed as destinations, Note that, because titles can often be parsed as destinations,

if you try to omit the destination and keep the title, you'll if you try to omit the destination and keep the title, you'll

get unexpected results: get unexpected results:

. ```````````````````````````````` example

[link]("title") [link]("title")

. .

. ````````````````````````````````

Titles may be in single quotes, double quotes, or parentheses: Titles may be in single quotes, double quotes, or parentheses:

. ```````````````````````````````` example

[link](/url "title") [link](/url "title")

[link](/url 'title') [link](/url 'title')

[link](/url (title)) [link](/url (title))

. .

. ````````````````````````````````

Backslash escapes and entity and numeric character references Backslash escapes and entity and numeric character references

may be used in titles: may be used in titles:

. ```````````````````````````````` example

[link](/url "title \""") [link](/url "title \""")

. .

. ````````````````````````````````

Nested balanced quotes are not allowed without escaping: Nested balanced quotes are not allowed without escaping:

. ```````````````````````````````` example

[link](/url "title "and" title") [link](/url "title "and" title")

. .

[link](/url "title "and" title")

. ````````````````````````````````

But it is easy to work around this by using a different quote type: But it is easy to work around this by using a different quote type:

. ```````````````````````````````` example

[link](/url 'title "and" title') [link](/url 'title "and" title')

. .

. ````````````````````````````````

(Note: `Markdown.pl` did allow double quotes inside a double-quoted (Note: `Markdown.pl` did allow double quotes inside a double-quoted

title, and its test suite included a test demonstrating this. title, and its test suite included a test demonstrating this.

But it is hard to see a good rationale for the extra complexity this But it is hard to see a good rationale for the extra complexity this

brings, since there are already many ways---backslash escaping, brings, since there are already many ways---backslash escaping,

entity and numeric character references, or using a different entity and numeric character references, or using a different

quote type for the enclosing title---to write titles containing quote type for the enclosing title---to write titles containing

double quotes. `Markdown.pl`'s handling of titles has a number double quotes. `Markdown.pl`'s handling of titles has a number

of other strange features. For example, it allows single-quoted of other strange features. For example, it allows single-quoted

titles in inline links, but not reference links. And, in titles in inline links, but not reference links. And, in

reference links but not inline links, it allows a title to begin reference links but not inline links, it allows a title to begin

with `"` and end with `)`. `Markdown.pl` 1.0.1 even allows with `"` and end with `)`. `Markdown.pl` 1.0.1 even allows

titles with no closing quotation mark, though 1.0.2b8 does not. titles with no closing quotation mark, though 1.0.2b8 does not.

It seems preferable to adopt a simple, rational rule that works It seems preferable to adopt a simple, rational rule that works

the same way in inline links and link reference definitions.) the same way in inline links and link reference definitions.)

[Whitespace] is allowed around the destination and title: [Whitespace] is allowed around the destination and title:

. ```````````````````````````````` example

[link]( /uri [link]( /uri

"title" ) "title" )

. .

. ````````````````````````````````

But it is not allowed between the link text and the But it is not allowed between the link text and the

following parenthesis: following parenthesis:

. ```````````````````````````````` example

[link] (/uri) [link] (/uri)

. .

[link] (/uri)

. ````````````````````````````````

The link text may contain balanced brackets, but not unbalanced ones, The link text may contain balanced brackets, but not unbalanced ones,

unless they are escaped: unless they are escaped:

. ```````````````````````````````` example

[link [foo [bar]]](/uri) [link [foo [bar]]](/uri)

. .

link [foo [bar]]

. ````````````````````````````````

. ```````````````````````````````` example

[link] bar](/uri) [link] bar](/uri)

. .

[link] bar](/uri)

. ````````````````````````````````

. ```````````````````````````````` example

[link [bar](/uri) [link [bar](/uri)

. .

[link bar

. ````````````````````````````````

. ```````````````````````````````` example

[link \[bar](/uri) [link \[bar](/uri)

. .

link [bar

. ````````````````````````````````

The link text may contain inline content: The link text may contain inline content:

. ```````````````````````````````` example

[link *foo **bar** `#`*](/uri) [link *foo **bar** `#`*](/uri)

. .

link foo bar #

. ````````````````````````````````

. ```````````````````````````````` example

[![moon](moon.jpg)](/uri) [![moon](moon.jpg)](/uri)

. .

. ````````````````````````````````

However, links may not contain other links, at any level of nesting. However, links may not contain other links, at any level of nesting.

. ```````````````````````````````` example

[foo [bar](/uri)](/uri) [foo [bar](/uri)](/uri)

. .

[foo bar](/uri)

. ````````````````````````````````

. ```````````````````````````````` example

[foo *[bar [baz](/uri)](/uri)*](/uri) [foo *[bar [baz](/uri)](/uri)*](/uri)

. .

[foo [bar baz](/uri)](/uri)

. ````````````````````````````````

. ```````````````````````````````` example

![[[foo](uri1)](uri2)](uri3) ![[[foo](uri1)](uri2)](uri3)

. .

[foo](uri2)

. ````````````````````````````````

These cases illustrate the precedence of link text grouping over These cases illustrate the precedence of link text grouping over

emphasis grouping: emphasis grouping:

. ```````````````````````````````` example

*[foo*](/uri) *[foo*](/uri)

. .

*foo*

. ````````````````````````````````

. ```````````````````````````````` example

[foo *bar](baz*) [foo *bar](baz*)

. .

foo *bar

. ````````````````````````````````

Note that brackets that *aren't* part of links do not take Note that brackets that *aren't* part of links do not take

precedence: precedence:

. ```````````````````````````````` example

*foo [bar* baz] *foo [bar* baz]

. .

foo [bar baz]

. ````````````````````````````````

These cases illustrate the precedence of HTML tags, code spans, These cases illustrate the precedence of HTML tags, code spans,

and autolinks over link grouping: and autolinks over link grouping:

. ```````````````````````````````` example

[foo [foo

. .

[foo

. ````````````````````````````````

. ```````````````````````````````` example

[foo`](/uri)` [foo`](/uri)`

. .

[foo](/uri)

. ````````````````````````````````

. ```````````````````````````````` example

[foo [foo

. .

[foohttp://example.com/?search= ](uri)

. ````````````````````````````````

There are three kinds of [reference link](@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](@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.

A [link label](@link-label) begins with a left bracket (`[`) and ends A [link label](@) begins with a left bracket (`[`) and ends

with the first right bracket (`]`) that is not backslash-escaped. with the first right bracket (`]`) that is not backslash-escaped.

Between these brackets there must be at least one [non-whitespace character]. Between these brackets there must be at least one [non-whitespace character].

Unescaped square bracket characters are not allowed in Unescaped square bracket characters are not allowed in

[link label]s. A link label can have at most 999 [link labels]. A link label can have at most 999

characters inside the square brackets. characters inside the square brackets.

One label [matches](@matches) One label [matches](@)

another just in case their normalized forms are equal. To normalize a another just in case their normalized forms are equal. To normalize a

label, perform the *Unicode case fold* and collapse consecutive internal label, perform the *Unicode case fold* and collapse consecutive internal

[whitespace] to a single space. If there are multiple [whitespace] to a single space. If there are multiple

matching reference link definitions, the one that comes first in the matching reference link definitions, the one that comes first in the

document is used. (It is desirable in such cases to emit a warning.) document is used. (It is desirable in such cases to emit a warning.)

The contents of the first link label are parsed as inlines, which are 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 are provided by the used as the link's text. The link's URI and title are provided by the

matching [link reference definition]. matching [link reference definition].

Here is a simple example: Here is a simple example:

. ```````````````````````````````` example

[foo][bar] [foo][bar]

[bar]: /url "title" [bar]: /url "title"

. .

. ````````````````````````````````

The rules for the [link text] are the same as with The rules for the [link text] are the same as with

[inline link]s. Thus: [inline links]. Thus:

The link text may contain balanced brackets, but not unbalanced ones, The link text may contain balanced brackets, but not unbalanced ones,

unless they are escaped: unless they are escaped:

. ```````````````````````````````` example

[link [foo [bar]]][ref] [link [foo [bar]]][ref]

[ref]: /uri [ref]: /uri

. .

link [foo [bar]]

. ````````````````````````````````

. ```````````````````````````````` example

[link \[bar][ref] [link \[bar][ref]

[ref]: /uri [ref]: /uri

. .

link [bar

. ````````````````````````````````

The link text may contain inline content: The link text may contain inline content:

. ```````````````````````````````` example

[link *foo **bar** `#`*][ref] [link *foo **bar** `#`*][ref]

[ref]: /uri [ref]: /uri

. .

link foo bar #

. ````````````````````````````````

. ```````````````````````````````` example

[![moon](moon.jpg)][ref] [![moon](moon.jpg)][ref]

[ref]: /uri [ref]: /uri

. .

. ````````````````````````````````

However, links may not contain other links, at any level of nesting. However, links may not contain other links, at any level of nesting.

. ```````````````````````````````` example

[foo [bar](/uri)][ref] [foo [bar](/uri)][ref]

[ref]: /uri [ref]: /uri

. .

[foo bar]ref

. ````````````````````````````````

. ```````````````````````````````` example

[foo *bar [baz][ref]*][ref] [foo *bar [baz][ref]*][ref]

[ref]: /uri [ref]: /uri

. .

[foo bar baz]ref

. ````````````````````````````````

(In the examples above, we have two [shortcut reference link]s (In the examples above, we have two [shortcut reference links]

instead of one [full reference link].) instead of one [full reference link].)

The following cases illustrate the precedence of link text grouping over The following cases illustrate the precedence of link text grouping over

emphasis grouping: emphasis grouping:

. ```````````````````````````````` example

*[foo*][ref] *[foo*][ref]

[ref]: /uri [ref]: /uri

. .

*foo*

. ````````````````````````````````

. ```````````````````````````````` example

[foo *bar][ref] [foo *bar][ref]

[ref]: /uri [ref]: /uri

. .

foo *bar

. ````````````````````````````````

These cases illustrate the precedence of HTML tags, code spans, These cases illustrate the precedence of HTML tags, code spans,

and autolinks over link grouping: and autolinks over link grouping:

. ```````````````````````````````` example

[foo [foo

[ref]: /uri [ref]: /uri

. .

[foo

. ````````````````````````````````

. ```````````````````````````````` example

[foo`][ref]` [foo`][ref]`

[ref]: /uri [ref]: /uri

. .

[foo][ref]

. ````````````````````````````````

. ```````````````````````````````` example

[foo [foo

[ref]: /uri [ref]: /uri

. .

[foohttp://example.com/?sea rch=][ref]

. ````````````````````````````````

Matching is case-insensitive: Matching is case-insensitive:

. ```````````````````````````````` example

[foo][BaR] [foo][BaR]

[bar]: /url "title" [bar]: /url "title"

. .

. ````````````````````````````````

Unicode case fold is used: Unicode case fold is used:

. ```````````````````````````````` example

[Толпой][Толпой] is a Russian word. [Толпой][Толпой] is a Russian word.

[ТОЛПОЙ]: /url [ТОЛПОЙ]: /url

. .

Толпой is a Russian word.

. ````````````````````````````````

Consecutive internal [whitespace] is treated as one space for Consecutive internal [whitespace] is treated as one space for

purposes of determining matching: purposes of determining matching:

. ```````````````````````````````` example

[Foo [Foo

bar]: /url bar]: /url

[Baz][Foo bar] [Baz][Foo bar]

. .

Baz

. ````````````````````````````````

No [whitespace] is allowed between the [link text] and the No [whitespace] is allowed between the [link text] and the

[link label]: [link label]:

. ```````````````````````````````` example

[foo] [bar] [foo] [bar]

[bar]: /url "title" [bar]: /url "title"

. .

[foo] bar

. ````````````````````````````````

. ```````````````````````````````` example

[foo] [foo]

[bar] [bar]

[bar]: /url "title" [bar]: /url "title"

. .

[foo]

bar

. ````````````````````````````````

This is a departure from John Gruber's original Markdown syntax This is a departure from John Gruber's original Markdown syntax

description, which explicitly allows whitespace between the link description, which explicitly allows whitespace between the link

text and the link label. It brings reference links in line with text and the link label. It brings reference links in line with

[inline link]s, which (according to both original Markdown and [inline links], which (according to both original Markdown and

this spec) cannot have whitespace after the link text. More this spec) cannot have whitespace after the link text. More

importantly, it prevents inadvertent capture of consecutive importantly, it prevents inadvertent capture of consecutive

[shortcut reference link]s. If whitespace is allowed between the [shortcut reference links]. If whitespace is allowed between the

link text and the link label, then in the following we will have link text and the link label, then in the following we will have

a single reference link, not two shortcut reference links, as a single reference link, not two shortcut reference links, as

intended: intended:

``` markdown ``` markdown

[foo] [foo]

[bar] [bar]

[foo]: /url1 [foo]: /url1

[bar]: /url2 [bar]: /url2

``` ```

(Note that [shortcut reference link]s were introduced by Gruber (Note that [shortcut reference links] were introduced by Gruber

himself in a beta version of `Markdown.pl`, but never included himself in a beta version of `Markdown.pl`, but never included

in the official syntax description. Without shortcut reference in the official syntax description. Without shortcut reference

links, it is harmless to allow space between the link text and links, it is harmless to allow space between the link text and

link label; but once shortcut references are introduced, it is link label; but once shortcut references are introduced, it is

too dangerous to allow this, as it frequently leads to too dangerous to allow this, as it frequently leads to

unintended results.) unintended results.)

When there are multiple matching [link reference definition]s, When there are multiple matching [link reference definitions],

the first is used: the first is used:

. ```````````````````````````````` example

[foo]: /url1 [foo]: /url1

[foo]: /url2 [foo]: /url2

[bar][foo] [bar][foo]

. .

bar

. ````````````````````````````````

Note that matching is performed on normalized strings, not parsed Note that matching is performed on normalized strings, not parsed

inline content. So the following does not match, even though the inline content. So the following does not match, even though the

labels define equivalent inline content: labels define equivalent inline content:

. ```````````````````````````````` example

[bar][foo\!] [bar][foo\!]

[foo!]: /url [foo!]: /url

. .

[bar][foo!]

. ````````````````````````````````

[Link label]s cannot contain brackets, unless they are [Link labels] cannot contain brackets, unless they are

backslash-escaped: backslash-escaped:

. ```````````````````````````````` example

[foo][ref[] [foo][ref[]

[ref[]: /uri [ref[]: /uri

. .

[foo][ref[]

[ref[]: /uri

. ````````````````````````````````

. ```````````````````````````````` example

[foo][ref[bar]] [foo][ref[bar]]

[ref[bar]]: /uri [ref[bar]]: /uri

. .

[foo][ref[bar]]

[ref[bar]]: /uri

. ````````````````````````````````

. ```````````````````````````````` example

[[[foo]]] [[[foo]]]

[[[foo]]]: /url [[[foo]]]: /url

. .

[[[foo]]]

[[[foo]]]: /url

. ````````````````````````````````

. ```````````````````````````````` example

[foo][ref\[] [foo][ref\[]

[ref\[]: /uri [ref\[]: /uri

. .

. ````````````````````````````````

Note that in this example `]` is not backslash-escaped: Note that in this example `]` is not backslash-escaped:

. ```````````````````````````````` example

[bar\\]: /uri [bar\\]: /uri

[bar\\] [bar\\]

. .

bar\

. ````````````````````````````````

A [link label] must contain at least one [non-whitespace character]: A [link label] must contain at least one [non-whitespace character]:

. ```````````````````````````````` example

[] []

[]: /uri []: /uri

. .

[]

[]: /uri

. ````````````````````````````````

. ```````````````````````````````` example

[ [

] ]

[ [

]: /uri ]: /uri

. .

[

]

[

]: /uri

. ````````````````````````````````

A [collapsed reference link](@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 first 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

[foo][] [foo][]

[foo]: /url "title" [foo]: /url "title"

. .

. ````````````````````````````````

. ```````````````````````````````` example

[*foo* bar][] [*foo* bar][]

[*foo* bar]: /url "title" [*foo* bar]: /url "title"

. .

foo bar

. ````````````````````````````````

The link labels are case-insensitive: The link labels are case-insensitive:

. ```````````````````````````````` example

[Foo][] [Foo][]

[foo]: /url "title" [foo]: /url "title"

. .

Foo

. ````````````````````````````````

As with full reference links, [whitespace] is not As with full reference links, [whitespace] is not

allowed between the two sets of brackets: allowed between the two sets of brackets:

. ```````````````````````````````` example

[foo] [foo]

[] []

[foo]: /url "title" [foo]: /url "title"

. .

[]

. ````````````````````````````````

A [shortcut reference link](@shortcut-reference-link) A [shortcut reference link](@)

consists of a [link label] that [matches] a consists of a [link label] that [matches] a

[link reference definition] elsewhere in the [link reference definition] elsewhere in the

document and is not followed by `[]` or a link label. document and is not followed by `[]` or a link label.

The contents of the first link label are parsed as inlines, The contents of the first link label are parsed as inlines,

which are used as the link's text. the link's URI and title which are used as the link's text. the link's URI and title

are provided by the matching link reference definition. are provided by the matching link reference definition.

Thus, `[foo]` is equivalent to `[foo][]`. Thus, `[foo]` is equivalent to `[foo][]`.

. ```````````````````````````````` example

[foo] [foo]

[foo]: /url "title" [foo]: /url "title"

. .

. ````````````````````````````````

. ```````````````````````````````` example

[*foo* bar] [*foo* bar]

[*foo* bar]: /url "title" [*foo* bar]: /url "title"

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

[[*foo* bar]] [[*foo* bar]]

[*foo* bar]: /url "title" [*foo* bar]: /url "title"

. .

[foo bar]

. ````````````````````````````````

. ```````````````````````````````` example

[[bar [foo] [[bar [foo]

[foo]: /url [foo]: /url

. .

[[bar foo

. ````````````````````````````````

The link labels are case-insensitive: The link labels are case-insensitive:

. ```````````````````````````````` example

[Foo] [Foo]

[foo]: /url "title" [foo]: /url "title"

. .

Foo

. ````````````````````````````````

A space after the link text should be preserved: A space after the link text should be preserved:

. ```````````````````````````````` example

[foo] bar [foo] bar

[foo]: /url [foo]: /url

. .

foo bar

. ````````````````````````````````

If you just want bracketed text, you can backslash-escape the If you just want bracketed text, you can backslash-escape the

opening bracket to avoid links: opening bracket to avoid links:

. ```````````````````````````````` example

\[foo] \[foo]

[foo]: /url "title" [foo]: /url "title"

. .

[foo]

. ````````````````````````````````

Note that this is a link, because a link label ends with the first Note that this is a link, because a link label ends with the first

following closing bracket: following closing bracket:

. ```````````````````````````````` example

[foo*]: /url [foo*]: /url

*[foo*] *[foo*]

. .

*foo*

. ````````````````````````````````

Full references take precedence over shortcut references: Full references take precedence over shortcut references:

. ```````````````````````````````` example

[foo][bar] [foo][bar]

[foo]: /url1 [foo]: /url1

[bar]: /url2 [bar]: /url2

. .

http://foo.ba r.baz/test?q=hello&id=22&boolean

. ````````````````````````````````

In the following case `[bar][baz]` is parsed as a reference, In the following case `[bar][baz]` is parsed as a reference,

`[foo]` as normal text: `[foo]` as normal text:

. ```````````````````````````````` example

[foo][bar][baz] [foo][bar][baz]

[baz]: /url [baz]: /url

. .

[foo]bar

. ````````````````````````````````

Here, though, `[foo][bar]` is parsed as a reference, since Here, though, `[foo][bar]` is parsed as a reference, since

`[bar]` is defined: `[bar]` is defined:

. ```````````````````````````````` example

[foo][bar][baz] [foo][bar][baz]

[baz]: /url1 [baz]: /url1

[bar]: /url2 [bar]: /url2

. .

foo baz

. ````````````````````````````````

Here `[foo]` is not parsed as a shortcut reference, because it Here `[foo]` is not parsed as a shortcut reference, because it

is followed by a link label (even though `[bar]` is not defined): is followed by a link label (even though `[bar]` is not defined):

. ```````````````````````````````` example

[foo][bar][baz] [foo][bar][baz]

[baz]: /url1 [baz]: /url1

[foo]: /url2 [foo]: /url2

. .

[foo]bar

. ````````````````````````````````

## Images ## Images

Syntax for images is like the syntax for links, with one Syntax for images is like the syntax for links, with one

difference. Instead of [link text], we have an difference. Instead of [link text], we have an

[image description](@image-description). The rules for this are the [image description](@). The rules for this are the

same as for [link text], except that (a) an same as for [link text], except that (a) an

image description starts with `![` rather than `[`, and image description starts with `![` rather than `[`, and

(b) an image description may contain links. (b) an image description may contain links.

An image description has inline elements An image description has inline elements

as its contents. When an image is rendered to HTML, as its contents. When an image is rendered to HTML,

this is standardly used as the image's `alt` attribute. this is standardly used as the image's `alt` attribute.

. ```````````````````````````````` example

![foo](/url "title") ![foo](/url "title")

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

![foo *bar*] ![foo *bar*]

[foo *bar*]: train.jpg "train & tracks" [foo *bar*]: train.jpg "train & tracks"

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

![foo ![bar](/url)](/url2) ![foo ![bar](/url)](/url2)

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

![foo [bar](/url)](/url2) ![foo [bar](/url)](/url2)

. .

foo bar

. ````````````````````````````````

Though this spec is concerned with parsing, not rendering, it is Though this spec is concerned with parsing, not rendering, it is

recommended that in rendering to HTML, only the plain string content recommended that in rendering to HTML, only the plain string content

of the [image description] be used. Note that in of the [image description] be used. Note that in

the above example, the alt attribute's value is `foo bar`, not `foo the above example, the alt attribute's value is `foo bar`, not `foo

[bar](/url)` or `foo bar`. Only the plain string [bar](/url)` or `foo bar`. Only the plain string

content is rendered, without formatting. content is rendered, without formatting.

. ```````````````````````````````` example

![foo *bar*][] ![foo *bar*][]

[foo *bar*]: train.jpg "train & tracks" [foo *bar*]: train.jpg "train & tracks"

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

![foo *bar*][foobar] ![foo *bar*][foobar]

[FOOBAR]: train.jpg "train & tracks" [FOOBAR]: train.jpg "train & tracks"

. .

foo bar

. ````````````````````````````````

. ```````````````````````````````` example

![foo](train.jpg) ![foo](train.jpg)

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

My ![foo bar](/path/to/train.jpg "title" ) My ![foo bar](/path/to/train.jpg "title" )

. .

My foo bar

. ````````````````````````````````

. ```````````````````````````````` example

![foo]() ![foo]()

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

![](/url) ![](/url)

. .

. ````````````````````````````````

Reference-style: Reference-style:

. ```````````````````````````````` example

![foo][bar] ![foo][bar]

[bar]: /url [bar]: /url

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

![foo][bar] ![foo][bar]

[BAR]: /url [BAR]: /url

. .

foo

. ````````````````````````````````

Collapsed: Collapsed:

. ```````````````````````````````` example

![foo][] ![foo][]

[foo]: /url "title" [foo]: /url "title"

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

![*foo* bar][] ![*foo* bar][]

[*foo* bar]: /url "title" [*foo* bar]: /url "title"

. .

foo bar

. ````````````````````````````````

The labels are case-insensitive: The labels are case-insensitive:

. ```````````````````````````````` example

![Foo][] ![Foo][]

[foo]: /url "title" [foo]: /url "title"

. .

Foo

. ````````````````````````````````

As with reference links, [whitespace] is not allowed As with reference links, [whitespace] is not allowed

between the two sets of brackets: between the two sets of brackets:

. ```````````````````````````````` example

![foo] ![foo]

[] []

[foo]: /url "title" [foo]: /url "title"

. .

foo

[]

. ````````````````````````````````

Shortcut: Shortcut:

. ```````````````````````````````` example

![foo] ![foo]

[foo]: /url "title" [foo]: /url "title"

. .

foo

. ````````````````````````````````

. ```````````````````````````````` example

![*foo* bar] ![*foo* bar]

[*foo* bar]: /url "title" [*foo* bar]: /url "title"

. .

foo bar

. ````````````````````````````````

Note that link labels cannot contain unescaped brackets: Note that link labels cannot contain unescaped brackets:

. ```````````````````````````````` example

![[foo]] ![[foo]]

[[foo]]: /url "title" [[foo]]: /url "title"

. .

![[foo]]

[[foo]]: /url "title"

. ````````````````````````````````

The link labels are case-insensitive: The link labels are case-insensitive:

. ```````````````````````````````` example

![Foo] ![Foo]

[foo]: /url "title" [foo]: /url "title"

. .

Foo

. ````````````````````````````````

If you just want bracketed text, you can backslash-escape the If you just want bracketed text, you can backslash-escape the

opening `!` and `[`: opening `!` and `[`:

. ```````````````````````````````` example

\!\[foo] \!\[foo]

[foo]: /url "title" [foo]: /url "title"

. .

![foo]

. ````````````````````````````````

If you want a link after a literal `!`, backslash-escape the If you want a link after a literal `!`, backslash-escape the

`!`: `!`:

. ```````````````````````````````` example

\![foo] \![foo]

[foo]: /url "title" [foo]: /url "title"

. .

!foo

. ````````````````````````````````

## Autolinks ## Autolinks

[Autolink](@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](@uri-autolink) consists of `<`, followed by an A [URI autolink](@) consists of `<`, followed by an

[absolute URI] not containing `<`, followed by `>`. It is parsed as [absolute URI] not containing `<`, 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](@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 than ASCII followed by zero or more characters other than ASCII

[whitespace] and control characters, `<`, and `>`. If [whitespace] and control characters, `<`, and `>`. If

the URI includes these characters, you must use percent-encoding the URI includes these characters, they must be percent-encoded

(e.g. `%20` for a space). (e.g. `%20` for a space).

The following [schemes](@scheme) For purposes of this spec, a [scheme](@) is any sequence

are recognized (case-insensitive): of 2--32 characters beginning with an ASCII letter and followed

`coap`, `doi`, `javascript`, `aaa`, `aaas`, `about`, `acap`, `cap`, by any combination of ASCII letters, digits, or the symbols plus

`cid`, `crid`, `data`, `dav`, `dict`, `dns`, `file`, `ftp`, `geo`, `go`, ("+"), period ("."), or hyphen ("-").

`gopher`, `h323`, `http`, `https`, `iax`, `icap`, `im`, `imap`, `info`,

`ipp`, `iris`, `iris.beep`, `iris.xpc`, `iris.xpcs`, `iris.lwz`, `ldap`,

`mailto`, `mid`, `msrp`, `msrps`, `mtqp`, `mupdate`, `news`, `nfs`,

`ni`, `nih`, `nntp`, `opaquelocktoken`, `pop`, `pres`, `rtsp`,

`service`, `session`, `shttp`, `sieve`, `sip`, `sips`, `sms`, `snmp`,`

soap.beep`, `soap.beeps`, `tag`, `tel`, `telnet`, `tftp`, `thismessage`,

`tn3270`, `tip`, `tv`, `urn`, `vemmi`, `ws`, `wss`, `xcon`,

`xcon-userid`, `xmlrpc.beep`, `xmlrpc.beeps`, `xmpp`, `z39.50r`,

`z39.50s`, `adiumxtra`, `afp`, `afs`, `aim`, `apt`,` attachment`, `aw`,

`beshare`, `bitcoin`, `bolo`, `callto`, `chrome`,` chrome-extension`,

`com-eventbrite-attendee`, `content`, `cvs`,` dlna-playsingle`,

`dlna-playcontainer`, `dtn`, `dvb`, `ed2k`, `facetime`, `feed`,

`finger`, `fish`, `gg`, `git`, `gizmoproject`, `gtalk`, `hcp`, `icon`,

`ipn`, `irc`, `irc6`, `ircs`, `itms`, `jar`, `jms`, `keyparc`, `lastfm`,

`ldaps`, `magnet`, `maps`, `market`,` message`, `mms`, `ms-help`,

`msnim`, `mumble`, `mvn`, `notes`, `oid`, `palm`, `paparazzi`,

`platform`, `proxy`, `psyc`, `query`, `res`, `resource`, `rmi`, `rsync`,

`rtmp`, `secondlife`, `sftp`, `sgn`, `skype`, `smb`, `soldat`,

`spotify`, `ssh`, `steam`, `svn`, `teamspeak`, `things`, `udp`,

`unreal`, `ut2004`, `ventrilo`, `view-source`, `webcal`, `wtai`,

`wyciwyg`, `xfire`, `xri`, `ymsgr`.

Here are some valid autolinks: Here are some valid autolinks:

. ```````````````````````````````` example

. .

http://foo.bar.baz

. ````````````````````````````````

. ```````````````````````````````` example

. .

. ````````````````````````````````

. ```````````````````````````````` example

. .

irc://foo.bar:2233/baz

. ````````````````````````````````

Uppercase is also fine: Uppercase is also fine:

. ```````````````````````````````` example

. .

MAILTO:[email protected]

````````````````````````````````

Note that many strings that count as [absolute URIs] for

purposes of this spec are not valid URIs, because their

schemes are not registered or because of other problems

with their syntax:

```````````````````````````````` example

. .

a+b+c:d

````````````````````````````````

Spaces are not allowed in autolinks: ```````````````````````````````` example

made-up-scheme://foo,bar

````````````````````````````````

```````````````````````````````` example

. .

http://../

````````````````````````````````

```````````````````````````````` example

localhost:5001/foo

````````````````````````````````

Spaces are not allowed in autolinks:

```````````````````````````````` example

. .

<http://foo.bar/baz bim>

. ````````````````````````````````

Backslash-escapes do not work inside autolinks: Backslash-escapes do not work inside autolinks:

. ```````````````````````````````` example

. .

http://example.com/\[\

. ````````````````````````````````

An [email autolink](@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](@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

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 )):

/^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0- 9])? /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0- 9])?

(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/ (?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/

Examples of email autolinks: Examples of email autolinks:

. ```````````````````````````````` example

. .

. ````````````````````````````````

. ```````````````````````````````` example

. .

. ````````````````````````````````

Backslash-escapes do not work inside email autolinks: Backslash-escapes do not work inside email autolinks:

. ```````````````````````````````` example

. .

<[email protected]>

. ````````````````````````````````

These are not autolinks: These are not autolinks:

. ```````````````````````````````` example

<> <>

. .

. ````````````````````````````````

<heck://bing.bong>

. ```````````````````````````````` example

< http://foo.bar > < http://foo.bar >

. .

< http://foo.bar >

. ````````````````````````````````

```````````````````````````````` example

. .

<m:abc>

````````````````````````````````

```````````````````````````````` example

. .

<foo.bar.baz>

. ````````````````````````````````

<localhost:5001/foo>

. ```````````````````````````````` example

http://example.com http://example.com

. .

http://example.com

. ````````````````````````````````

. ```````````````````````````````` example

. .