spec.txt



---
title: CommonMark Spec
author:
- John MacFarlane
version: 0.13
date: 2014-12-10
...

# Introduction

## What is Markdown?

Markdown is a plain text format for writing structured documents,
based on conventions used for indicating formatting in email and
usenet posts.  It was developed in 2004 by John Gruber, who wrote
the first Markdown-to-HTML converter in perl, and it soon became
widely used in websites.  By 2014 there were dozens of
implementations in many languages.  Some of them extended basic
Markdown syntax with conventions for footnotes, definition lists,
tables, and other constructs, and some allowed output not just in
HTML but in LaTeX and many other formats.

## Why is a spec needed?

John Gruber's [canonical description of Markdown's
syntax](http://daringfireball.net/projects/markdown/syntax)
does not specify the syntax unambiguously.  Here are some examples of
questions it does not answer:

1.  How much indentation is needed for a sublist?  The spec says that
    continuation paragraphs need to be indented four spaces, but is
    not fully explicit about sublists.  It is natural to think that
    they, too, must be indented four spaces, but `Markdown.pl` does
    not require that.  This is hardly a "corner case," and divergences
    between implementations on this issue often lead to surprises for
    users in real documents. (See [this comment by John
    Gruber](http://article.gmane.org/gmane.text.markdown.general/1997).)

2.  Is a blank line needed before a block quote or header?
    Most implementations do not require the blank line.  However,
    this can lead to unexpected results in hard-wrapped text, and
    also to ambiguities in parsing (note that some implementations
    put the header inside the blockquote, while others do not).
    (John Gruber has also spoken [in favor of requiring the blank
    lines](http://article.gmane.org/gmane.text.markdown.general/2146).)

3.  Is a blank line needed before an indented code block?
    (`Markdown.pl` requires it, but this is not mentioned in the
    documentation, and some implementations do not require it.)

    ``` markdown
    paragraph
        code?
    ```

4.  What is the exact rule for determining when list items get
    wrapped in `<p>` tags?  Can a list be partially "loose" and partially
    "tight"?  What should we do with a list like this?

    ``` markdown
    1. one

    2. two
    3. three
    ```

    Or this?

    ``` markdown
    1.  one
        - a

        - b
    2.  two
    ```

    (There are some relevant comments by John Gruber
    [here](http://article.gmane.org/gmane.text.markdown.general/2554).)

5.  Can list markers be indented?  Can ordered list markers be right-aligned?

    ``` markdown
     8. item 1
     9. item 2
    10. item 2a
    ```

6.  Is this one list with a horizontal rule in its second item,
    or two lists separated by a horizontal rule?

    ``` markdown
    * a
    * * * * *
    * b
    ```

7.  When list markers change from numbers to bullets, do we have
    two lists or one?  (The Markdown syntax description suggests two,
    but the perl scripts and many other implementations produce one.)

    ``` markdown
    1. fee
    2. fie
    -  foe
    -  fum
    ```

8.  What are the precedence rules for the markers of inline structure?
    For example, is the following a valid link, or does the code span
    take precedence ?

    ``` markdown
    [a backtick (`)](/url) and [another backtick (`)](/url).
    ```

9.  What are the precedence rules for markers of emphasis and strong
    emphasis?  For example, how should the following be parsed?

    ``` markdown
    *foo *bar* baz*
    ```

10. What are the precedence rules between block-level and inline-level
    structure?  For example, how should the following be parsed?

    ``` markdown
    - `a long code span can contain a hyphen like this
      - and it can screw things up`
    ```

11. Can list items include section headers?  (`Markdown.pl` does not
    allow this, but does allow blockquotes to include headers.)

    ``` markdown
    - # Heading
    ```

12. Can list items be empty?

    ``` markdown
    * a
    *
    * b
    ```

13. Can link references be defined inside block quotes or list items?

    ``` markdown
    > Blockquote [foo].
    >
    > [foo]: /url
    ```

14. If there are multiple definitions for the same reference, which takes
    precedence?

    ``` markdown
    [foo]: /url1
    [foo]: /url2

    [foo][]
    ```

In the absence of a spec, early implementers consulted `Markdown.pl`
to resolve these ambiguities.  But `Markdown.pl` was quite buggy, and
gave manifestly bad results in many cases, so it was not a
satisfactory replacement for a spec.

Because there is no unambiguous spec, implementations have diverged
considerably.  As a result, users are often surprised to find that
a document that renders one way on one system (say, a github wiki)
renders differently on another (say, converting to docbook using
pandoc).  To make matters worse, because nothing in Markdown counts
as a "syntax error," the divergence often isn't discovered right away.

## About this document

This document attempts to specify Markdown syntax unambiguously.
It contains many examples with side-by-side Markdown and
HTML.  These are intended to double as conformance tests.  An
accompanying script `spec_tests.py` can be used to run the tests
against any Markdown program:

    python test/spec_tests.py --spec spec.txt --program PROGRAM

Since this document describes how Markdown is to be parsed into
an abstract syntax tree, it would have made sense to use an abstract
representation of the syntax tree instead of HTML.  But HTML is capable
of representing the structural distinctions we need to make, and the
choice of HTML for the tests makes it possible to run the tests against
an implementation without writing an abstract syntax tree renderer.

This document is generated from a text file, `spec.txt`, written
in Markdown with a small extension for the side-by-side tests.
The script `spec2md.pl` can be used to turn `spec.txt` into pandoc
Markdown, which can then be converted into other formats.

In the examples, the `→` character is used to represent tabs.

# Preliminaries

## Characters and lines

The input is a sequence of zero or more [lines](#line).

A [line](@line)
is a sequence of zero or more [characters](#character) followed by a
[line ending](#line-ending) or by the end of file.

A [character](@character) is a unicode code point.
This spec does not specify an encoding; it thinks of lines as composed
of characters rather than bytes.  A conforming parser may be limited
to a certain encoding.

A [line ending](@line-ending) is, depending on the platform, a
newline (`U+000A`), carriage return (`U+000D`), or
carriage return + newline.

For security reasons, a conforming parser must strip or replace the
Unicode character `U+0000`.

A line containing no characters, or a line containing only spaces
(`U+0020`) or tabs (`U+0009`), is called a [blank line](@blank-line).

The following definitions of character classes will be used in this spec:

A [whitespace character](@whitespace-character) is a space
(`U+0020`), tab (`U+0009`), carriage return (`U+000D`), or
newline (`U+000A`).

[Whitespace](@whitespace) is a sequence of one or more [whitespace
characters](#whitespace-character).

A [unicode whitespace character](@unicode-whitespace-character) is
any code point in the unicode `Zs` class, or a tab (`U+0009`),
carriage return (`U+000D`), newline (`U+000A`), or form feed
(`U+000C`).

[Unicode whitespace](@unicode-whitespace) is a sequence of one
or more [unicode whitespace characters](#unicode-whitespace-character).

A [non-space character](@non-space-character) is anything but `U+0020`.

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

A [punctuation character](@punctuation-character) is an [ASCII
punctuation character](#ascii-punctuation-character) or anything in
the unicode classes `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`.

## Tab expansion

Tabs in lines are expanded to spaces, with a tab stop of 4 characters:

.
→foo→baz→→bim
.
<pre><code>foo baz     bim
</code></pre>
.

.
    a→a
    ὐ→a
.
<pre><code>a   a
ὐ   a
</code></pre>
.

# Blocks and inlines

We can think of a document as a sequence of
[blocks](@block)---structural
elements like paragraphs, block quotations,
lists, headers, rules, and code blocks.  Blocks can contain other
blocks, or they can contain [inline](@inline) content:
words, spaces, links, emphasized text, images, and inline code.

## Precedence

Indicators of block structure always take precedence over indicators
of inline structure.  So, for example, the following is a list with
two items, not a list with one item containing a code span:

.
- `one
- two`
.
<ul>
<li>`one</li>
<li>two`</li>
</ul>
.

This means that parsing can proceed in two steps:  first, the block
structure of the document can be discerned; second, text lines inside
paragraphs, headers, and other block constructs can be parsed for inline
structure.  The second step requires information about link reference
definitions that will be available only at the end of the first
step.  Note that the first step requires processing lines in sequence,
but the second can be parallelized, since the inline parsing of
one block element does not affect the inline parsing of any other.

## Container blocks and leaf blocks

We can divide blocks into two types:
[container blocks](@container-block),
which can contain other blocks, and [leaf blocks](@leaf-block),
which cannot.

# Leaf blocks

This section describes the different kinds of leaf block that make up a
Markdown document.

## Horizontal rules

A line consisting of 0-3 spaces of indentation, followed by a sequence
of three or more matching `-`, `_`, or `*` characters, each followed
optionally by any number of spaces, forms a [horizontal
rule](@horizontal-rule).

.
***
---
___
.
<hr />
<hr />
<hr />
.

Wrong characters:

.
+++
.
<p>+++</p>
.

.
===
.
<p>===</p>
.

Not enough characters:

.
--
**
__
.
<p>--
**
__</p>
.

One to three spaces indent are allowed:

.
 ***
  ***
   ***
.
<hr />
<hr />
<hr />
.

Four spaces is too many:

.
    ***
.
<pre><code>***
</code></pre>
.

.
Foo
    ***
.
<p>Foo
***</p>
.

More than three characters may be used:

.
_____________________________________
.
<hr />
.

Spaces are allowed between the characters:

.
 - - -
.
<hr />
.

.
 **  * ** * ** * **
.
<hr />
.

.
-     -      -      -
.
<hr />
.

Spaces are allowed at the end:

.
- - - -    
.
<hr />
.

However, no other characters may occur in the line:

.
_ _ _ _ a

a------

---a---
.
<p>_ _ _ _ a</p>
<p>a------</p>
<p>---a---</p>
.

It is required that all of the
[non-space characters](#non-space-character) be the same.
So, this is not a horizontal rule:

.
 *-*
.
<p><em>-</em></p>
.

Horizontal rules do not need blank lines before or after:

.
- foo
***
- bar
.
<ul>
<li>foo</li>
</ul>
<hr />
<ul>
<li>bar</li>
</ul>
.

Horizontal rules can interrupt a paragraph:

.
Foo
***
bar
.
<p>Foo</p>
<hr />
<p>bar</p>
.

If a line of dashes that meets the above conditions for being a
horizontal rule could also be interpreted as the underline of a [setext
header](#setext-header), the interpretation as a
[setext-header](#setext-header) takes precedence. Thus, for example,
this is a setext header, not a paragraph followed by a horizontal rule:

.
Foo
---
bar
.
<h2>Foo</h2>
<p>bar</p>
.

When both a horizontal rule and a list item are possible
interpretations of a line, the horizontal rule is preferred:

.
* Foo
* * *
* Bar
.
<ul>
<li>Foo</li>
</ul>
<hr />
<ul>
<li>Bar</li>
</ul>
.

If you want a horizontal rule in a list item, use a different bullet:

.
- Foo
- * * *
.
<ul>
<li>Foo</li>
<li>
<hr />
</li>
</ul>
.

## ATX headers

An [ATX header](@atx-header)
consists of a string of characters, parsed as inline content, between an
opening sequence of 1--6 unescaped `#` characters and an optional
closing sequence of any number of `#` characters.  The opening sequence
of `#` characters cannot be followed directly by a nonspace character.
The optional closing sequence of `#`s must be preceded by a space and may be
followed by spaces only.  The opening `#` character may be indented 0-3
spaces.  The raw contents of the header are stripped of leading and
trailing spaces before being parsed as inline content.  The header level
is equal to the number of `#` characters in the opening sequence.

Simple headers:

.
# foo
## foo
### foo
#### foo
##### foo
###### foo
.
<h1>foo</h1>
<h2>foo</h2>
<h3>foo</h3>
<h4>foo</h4>
<h5>foo</h5>
<h6>foo</h6>
.

More than six `#` characters is not a header:

.
####### foo
.
<p>####### foo</p>
.

A space is required between the `#` characters and the header's
contents.  Note that many implementations currently do not require
the space.  However, the space was required by the [original ATX
implementation](http://www.aaronsw.com/2002/atx/atx.py), and it helps
prevent things like the following from being parsed as headers:

.
#5 bolt
.
<p>#5 bolt</p>
.

This is not a header, because the first `#` is escaped:

.
\## foo
.
<p>## foo</p>
.

Contents are parsed as inlines:

.
# foo *bar* \*baz\*
.
<h1>foo <em>bar</em> *baz*</h1>
.

Leading and trailing blanks are ignored in parsing inline content:

.
#                  foo                     
.
<h1>foo</h1>
.

One to three spaces indentation are allowed:

.
 ### foo
  ## foo
   # foo
.
<h3>foo</h3>
<h2>foo</h2>
<h1>foo</h1>
.

Four spaces are too much:

.
    # foo
.
<pre><code># foo
</code></pre>
.

.
foo
    # bar
.
<p>foo
# bar</p>
.

A closing sequence of `#` characters is optional:

.
## foo ##
  ###   bar    ###
.
<h2>foo</h2>
<h3>bar</h3>
.

It need not be the same length as the opening sequence:

.
# foo ##################################
##### foo ##
.
<h1>foo</h1>
<h5>foo</h5>
.

Spaces are allowed after the closing sequence:

.
### foo ###     
.
<h3>foo</h3>
.

A sequence of `#` characters with a nonspace character following it
is not a closing sequence, but counts as part of the contents of the
header:

.
### foo ### b
.
<h3>foo ### b</h3>
.

The closing sequence must be preceded by a space:

.
# foo#
.
<h1>foo#</h1>
.

Backslash-escaped `#` characters do not count as part
of the closing sequence:

.
### foo \###
## foo #\##
# foo \#
.
<h3>foo ###</h3>
<h2>foo ###</h2>
<h1>foo #</h1>
.

ATX headers need not be separated from surrounding content by blank
lines, and they can interrupt paragraphs:

.
****
## foo
****
.
<hr />
<h2>foo</h2>
<hr />
.

.
Foo bar
# baz
Bar foo
.
<p>Foo bar</p>
<h1>baz</h1>
<p>Bar foo</p>
.

ATX headers can be empty:

.
## 
#
### ###
.
<h2></h2>
<h1></h1>
<h3></h3>
.

## Setext headers

A [setext header](@setext-header)
consists of a line of text, containing at least one nonspace character,
with no more than 3 spaces indentation, followed by a [setext header
underline](#setext-header-underline).  The line of text must be
one that, were it not followed by the setext header underline,
would be interpreted as part of a paragraph:  it cannot be a code
block, header, blockquote, horizontal rule, or list.

A [setext header underline](@setext-header-underline) is a sequence of
`=` characters or a sequence of `-` characters, with no more than 3
spaces indentation and any number of trailing spaces.  If a line
containing a single `-` can be interpreted as an
empty [list item](#list-items), it should be interpreted this way
and not as a [setext header underline](#setext-header-underline).

The header is a level 1 header if `=` characters are used in the
[setext header underline](#setext-header-underline), and a level 2
header if `-` characters are used.  The contents of the header are the
result of parsing the first line as Markdown inline content.

In general, a setext header need not be preceded or followed by a
blank line.  However, it cannot interrupt a paragraph, so when a
setext header comes after a paragraph, a blank line is needed between
them.

Simple examples:

.
Foo *bar*
=========

Foo *bar*
---------
.
<h1>Foo <em>bar</em></h1>
<h2>Foo <em>bar</em></h2>
.

The underlining can be any length:

.
Foo
-------------------------

Foo
=
.
<h2>Foo</h2>
<h1>Foo</h1>
.

The header content can be indented up to three spaces, and need
not line up with the underlining:

.
   Foo
---

  Foo
-----

  Foo
  ===
.
<h2>Foo</h2>
<h2>Foo</h2>
<h1>Foo</h1>
.

Four spaces indent is too much:

.
    Foo
    ---

    Foo
---
.
<pre><code>Foo
---

Foo
</code></pre>
<hr />
.

The setext header underline can be indented up to three spaces, and
may have trailing spaces:

.
Foo
   ----      
.
<h2>Foo</h2>
.

Four spaces is too much:

.
Foo
     ---
.
<p>Foo
---</p>
.

The setext header underline cannot contain internal spaces:

.
Foo
= =

Foo
--- -
.
<p>Foo
= =</p>
<p>Foo</p>
<hr />
.

Trailing spaces in the content line do not cause a line break:

.
Foo  
-----
.
<h2>Foo</h2>
.

Nor does a backslash at the end:

.
Foo\
----
.
<h2>Foo\</h2>
.

Since indicators of block structure take precedence over
indicators of inline structure, the following are setext headers:

.
`Foo
----
`

<a title="a lot
---
of dashes"/>
.
<h2>`Foo</h2>
<p>`</p>
<h2>&lt;a title=&quot;a lot</h2>
<p>of dashes&quot;/&gt;</p>
.

The setext header underline cannot be a [lazy continuation
line](#lazy-continuation-line) in a list item or block quote:

.
> Foo
---
.
<blockquote>
<p>Foo</p>
</blockquote>
<hr />
.

.
- Foo
---
.
<ul>
<li>Foo</li>
</ul>
<hr />
.

A setext header cannot interrupt a paragraph:

.
Foo
Bar
---

Foo
Bar
===
.
<p>Foo
Bar</p>
<hr />
<p>Foo
Bar
===</p>
.

But in general a blank line is not required before or after:

.
---
Foo
---
Bar
---
Baz
.
<hr />
<h2>Foo</h2>
<h2>Bar</h2>
<p>Baz</p>
.

Setext headers cannot be empty:

.

====
.
<p>====</p>
.

Setext header text lines must not be interpretable as block
constructs other than paragraphs.  So, the line of dashes
in these examples gets interpreted as a horizontal rule:

.
---
---
.
<hr />
<hr />
.

.
- foo
-----
.
<ul>
<li>foo</li>
</ul>
<hr />
.

.
    foo
---
.
<pre><code>foo
</code></pre>
<hr />
.

.
> foo
-----
.
<blockquote>
<p>foo</p>
</blockquote>
<hr />
.

If you want a header with `> foo` as its literal text, you can
use backslash escapes:

.
\> foo
------
.
<h2>&gt; foo</h2>
.

## Indented code blocks

An [indented code block](@indented-code-block) is composed of one or more
[indented chunks](#indented-chunk) separated by blank lines.
An [indented chunk](@indented-chunk) is a sequence of non-blank lines,
each indented four or more spaces. The contents of the code block are
the literal contents of the lines, including trailing
[line endings](#line-ending), minus four spaces of indentation.
An indented code block has no attributes.

An indented code block cannot interrupt a paragraph, so there must be
a blank line between a paragraph and a following indented code block.
(A blank line is not needed, however, between a code block and a following
paragraph.)

.
    a simple
      indented code block
.
<pre><code>a simple
  indented code block
</code></pre>
.

The contents are literal text, and do not get parsed as Markdown:

.
    <a/>
    *hi*

    - one
.
<pre><code>&lt;a/&gt;
*hi*

- one
</code></pre>
.

Here we have three chunks separated by blank lines:

.
    chunk1

    chunk2
  
 
    chunk3
.
<pre><code>chunk1

chunk2


chunk3
</code></pre>
.

Any initial spaces beyond four will be included in the content, even
in interior blank lines:

.
    chunk1
      
      chunk2
.
<pre><code>chunk1
  
  chunk2
</code></pre>
.

An indented code block cannot interrupt a paragraph.  (This
allows hanging indents and the like.)

.
Foo
    bar

.
<p>Foo
bar</p>
.

However, any non-blank line with fewer than four leading spaces ends
the code block immediately.  So a paragraph may occur immediately
after indented code:

.
    foo
bar
.
<pre><code>foo
</code></pre>
<p>bar</p>
.

And indented code can occur immediately before and after other kinds of
blocks:

.
# Header
    foo
Header
------
    foo
----
.
<h1>Header</h1>
<pre><code>foo
</code></pre>
<h2>Header</h2>
<pre><code>foo
</code></pre>
<hr />
.

The first line can be indented more than four spaces:

.
        foo
    bar
.
<pre><code>    foo
bar
</code></pre>
.

Blank lines preceding or following an indented code block
are not included in it:

.

    
    foo
    

.
<pre><code>foo
</code></pre>
.

Trailing spaces are included in the code block's content:

.
    foo  
.
<pre><code>foo  
</code></pre>
.


## Fenced code blocks

A [code fence](@code-fence) is a sequence
of at least three consecutive backtick characters (`` ` ``) or
tildes (`~`).  (Tildes and backticks cannot be mixed.)
A [fenced code block](@fenced-code-block)
begins with a code fence, indented no more than three spaces.

The line with the opening code fence may optionally contain some text
following the code fence; this is trimmed of leading and trailing
spaces and called the [info string](@info-string).
The info string may not contain any backtick
characters.  (The reason for this restriction is that otherwise
some inline code would be incorrectly interpreted as the
beginning of a fenced code block.)

The content of the code block consists of all subsequent lines, until
a closing [code fence](#code-fence) of the same type as the code block
began with (backticks or tildes), and with at least as many backticks
or tildes as the opening code fence.  If the leading code fence is
indented N spaces, then up to N spaces of indentation are removed from
each line of the content (if present).  (If a content line is not
indented, it is preserved unchanged.  If it is indented less than N
spaces, all of the indentation is removed.)

The closing code fence may be indented up to three spaces, and may be
followed only by spaces, which are ignored.  If the end of the
containing block (or document) is reached and no closing code fence
has been found, the code block contains all of the lines after the
opening code fence until the end of the containing block (or
document).  (An alternative spec would require backtracking in the
event that a closing code fence is not found.  But this makes parsing
much less efficient, and there seems to be no real down side to the
behavior described here.)

A fenced code block may interrupt a paragraph, and does not require
a blank line either before or after.

The content of a code fence is treated as literal text, not parsed
as inlines.  The first word of the info string is typically used to
specify the language of the code sample, and rendered in the `class`
attribute of the `code` tag.  However, this spec does not mandate any
particular treatment of the info string.

Here is a simple example with backticks:

.
```
<
 >
```
.
<pre><code>&lt;
 &gt;
</code></pre>
.

With tildes:

.
~~~
<
 >
~~~
.
<pre><code>&lt;
 &gt;
</code></pre>
.

The closing code fence must use the same character as the opening
fence:

.
```
aaa
~~~
```
.
<pre><code>aaa
~~~
</code></pre>
.

.
~~~
aaa
```
~~~
.
<pre><code>aaa
```
</code></pre>
.

The closing code fence must be at least as long as the opening fence:

.
````
aaa
```
``````
.
<pre><code>aaa
```
</code></pre>
.

.