7.64 KB
<h1>CommonMark</h1>
<p>CommonMark is a rationalized version of Markdown syntax,
with a <a href="http://spec.commonmark.org/">spec</a> and BSD-licensed reference
implementations in C and JavaScript.</p>
<p><a href="http://try.commonmark.org/">Try it now!</a></p>
<p>For more details, see <a href="http://commonmark.org">http://commonmark.org</a>.</p>
<p>This repository contains the spec itself, along with tools for
running tests against the spec, and for creating HTML and PDF versions
of the spec.</p>
<p>The reference implementations live in separate repositories:</p>
<ul>
<li><a href="https://github.com/commonmark/cmark">https://github.com/commonmark/cmark</a> (C)</li>
<li><a href="https://github.com/commonmark/commonmark.js">https://github.com/commonmark/commonmark.js</a> (JavaScript)</li>
</ul>
<p>There is a list of third-party libraries
in a dozen different languages
<a href="https://github.com/commonmark/CommonMark/wiki/List-of-CommonMark-Implementations">here</a>.</p>
<h2>Running tests against the spec</h2>
<p><a href="http://spec.commonmark.org/">The spec</a> contains over 500 embedded examples which serve as conformance
tests. To run the tests using an executable <code>$PROG</code>:</p>
<pre><code>python3 test/spec_tests.py --program $PROG
</code></pre>
<p>If you want to extract the raw test data from the spec without
actually running the tests, you can do:</p>
<pre><code>python3 test/spec_tests.py --dump-tests
</code></pre>
<p>and you'll get all the tests in JSON format.</p>
<h2>The spec</h2>
<p>The source of <a href="http://spec.commonmark.org/">the spec</a> is <code>spec.txt</code>.  This is basically a Markdown
file, with code examples written in a shorthand form:</p>
<pre><code>```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````
</code></pre>
<p>To build an HTML version of the spec, do <code>make spec.html</code>.  To build a
PDF version, do <code>make spec.pdf</code>.  For both versions, you must
have the lua rock <code>lcmark</code> installed:  after installing lua and
lua rocks, <code>luarocks install lcmark</code>.  For the PDF you must also
have xelatex installed.</p>
<p>The spec is written from the point of view of the human writer, not
the computer reader.  It is not an algorithm---an English translation of
a computer program---but a declarative description of what counts as a block
quote, a code block, and each of the other structural elements that can
make up a Markdown document.</p>
<p>Because John Gruber's <a href="http://daringfireball.net/projects/markdown/syntax">canonical syntax
description</a> leaves
many aspects of the syntax undetermined, writing a precise spec requires
making a large number of decisions, many of them somewhat arbitrary.
In making them, we have appealed to existing conventions and
considerations of simplicity, readability, expressive power, and
consistency.  We have tried to ensure that &quot;normal&quot; documents in the many
incompatible existing implementations of Markdown will render, as far as
possible, as their authors intended.  And we have tried to make the rules
for different elements work together harmoniously.  In places where
different decisions could have been made (for example, the rules
governing list indentation), we have explained the rationale for
our choices.  In a few cases, we have departed slightly from the canonical
syntax description, in ways that we think further the goals of Markdown
as stated in that description.</p>
<p>For the most part, we have limited ourselves to the basic elements
described in Gruber's canonical syntax description, eschewing extensions
like footnotes and definition lists.  It is important to get the core
right before considering such things. However, we have included a visible
syntax for line breaks and fenced code blocks.</p>
<h2>Differences from original Markdown</h2>
<p>There are only a few places where this spec says things that contradict
the canonical syntax description:</p>
<ul>
<li>
<p>It allows all punctuation symbols to be backslash-escaped,
not just the symbols with special meanings in Markdown. We found
that it was just too hard to remember which symbols could be
escaped.</p>
</li>
<li>
<p>It introduces an alternative syntax for hard line
breaks, a backslash at the end of the line, supplementing the
two-spaces-at-the-end-of-line rule. This is motivated by persistent
complaints about the “invisible” nature of the two-space rule.</p>
</li>
<li>
<p>Link syntax has been made a bit more predictable (in a
backwards-compatible way). For example, <code>Markdown.pl</code> allows single
quotes around a title in inline links, but not in reference links.
This kind of difference is really hard for users to remember, so the
spec allows single quotes in both contexts.</p>
</li>
<li>
<p>The rule for HTML blocks differs, though in most real cases it
shouldn't make a difference. (See the section on HTML Blocks
for details.) The spec's proposal makes it easy to include Markdown
inside HTML block-level tags, if you want to, but also allows you to
exclude this. It also makes parsing much easier, avoiding
expensive backtracking.</p>
</li>
<li>
<p>It does not collapse adjacent bird-track blocks into a single
blockquote:</p>
<pre><code>&gt; this is two

&gt; blockquotes

&gt; this is a single
&gt;
&gt; blockquote with two paragraphs
</code></pre>
</li>
<li>
<p>Rules for content in lists differ in a few respects, though (as with
HTML blocks), most lists in existing documents should render as
intended. There is some discussion of the choice points and
differences in the subsection of List Items entitled Motivation.
We think that the spec's proposal does better than any existing
implementation in rendering lists the way a human writer or reader
would intuitively understand them. (We could give numerous examples
of perfectly natural looking lists that nearly every existing
implementation flubs up.)</p>
</li>
<li>
<p>Changing bullet characters, or changing from bullets to numbers or
vice versa, starts a new list. We think that is almost always going
to be the writer's intent.</p>
</li>
<li>
<p>The number that begins an ordered list item may be followed by
either <code>.</code> or <code>)</code>. Changing the delimiter style starts a new
list.</p>
</li>
<li>
<p>The start number of an ordered list is significant.</p>
</li>
<li>
<p>Fenced code blocks are supported, delimited by either
backticks (<code>```</code>) or tildes (<code>~~~</code>).</p>
</li>
</ul>
<h2>Contributing</h2>
<p>There is a <a href="http://talk.commonmark.org">forum for discussing
CommonMark</a>; you should use it instead of
github issues for questions and possibly open-ended discussions.
Use the <a href="http://github.com/commonmark/CommonMark/issues">github issue tracker</a>
only for simple, clear, actionable issues.</p>
<h2>Authors</h2>
<p>The spec was written by John MacFarlane, drawing on</p>
<ul>
<li>his experience writing and maintaining Markdown implementations in several
languages, including the first Markdown parser not based on regular
expression substitutions (<a href="http://github.com/jgm/pandoc">pandoc</a>) and
the first markdown parsers based on PEG grammars
(<a href="http://github.com/jgm/peg-markdown">peg-markdown</a>,
<a href="http://github.com/jgm/lunamark">lunamark</a>)</li>
<li>a detailed examination of the differences between existing Markdown
implementations using <a href="http://johnmacfarlane.net/babelmark2/">BabelMark 2</a>,
and</li>
<li>extensive discussions with David Greenspan, Jeff Atwood, Vicent
Marti, Neil Williams, and Benjamin Dumke-von der Ehe.</li>
</ul>
<p>Since the first announcement, many people have contributed ideas.
Kārlis Gaņģis was especially helpful in refining the rules for
emphasis, strong emphasis, links, and images.</p>

CommonMark

CommonMark is a rationalized version of Markdown syntax, with a spec and BSD-licensed reference implementations in C and JavaScript.

Try it now!

For more details, see http://commonmark.org.

This repository contains the spec itself, along with tools for running tests against the spec, and for creating HTML and PDF versions of the spec.

The reference implementations live in separate repositories:

There is a list of third-party libraries in a dozen different languages here.

Running tests against the spec

The spec contains over 500 embedded examples which serve as conformance tests. To run the tests using an executable $PROG:

python3 test/spec_tests.py --program $PROG

If you want to extract the raw test data from the spec without actually running the tests, you can do:

python3 test/spec_tests.py --dump-tests

and you'll get all the tests in JSON format.

The spec

The source of the spec is spec.txt. This is basically a Markdown file, with code examples written in a shorthand form:

```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````

To build an HTML version of the spec, do make spec.html. To build a PDF version, do make spec.pdf. For both versions, you must have the lua rock lcmark installed: after installing lua and lua rocks, luarocks install lcmark. For the PDF you must also have xelatex installed.

The spec is written from the point of view of the human writer, not the computer reader. It is not an algorithm---an English translation of a computer program---but a declarative description of what counts as a block quote, a code block, and each of the other structural elements that can make up a Markdown document.

Because John Gruber's canonical syntax description leaves many aspects of the syntax undetermined, writing a precise spec requires making a large number of decisions, many of them somewhat arbitrary. In making them, we have appealed to existing conventions and considerations of simplicity, readability, expressive power, and consistency. We have tried to ensure that "normal" documents in the many incompatible existing implementations of Markdown will render, as far as possible, as their authors intended. And we have tried to make the rules for different elements work together harmoniously. In places where different decisions could have been made (for example, the rules governing list indentation), we have explained the rationale for our choices. In a few cases, we have departed slightly from the canonical syntax description, in ways that we think further the goals of Markdown as stated in that description.

For the most part, we have limited ourselves to the basic elements described in Gruber's canonical syntax description, eschewing extensions like footnotes and definition lists. It is important to get the core right before considering such things. However, we have included a visible syntax for line breaks and fenced code blocks.

Differences from original Markdown

There are only a few places where this spec says things that contradict the canonical syntax description:

  • It allows all punctuation symbols to be backslash-escaped, not just the symbols with special meanings in Markdown. We found that it was just too hard to remember which symbols could be escaped.

  • It introduces an alternative syntax for hard line breaks, a backslash at the end of the line, supplementing the two-spaces-at-the-end-of-line rule. This is motivated by persistent complaints about the “invisible” nature of the two-space rule.

  • Link syntax has been made a bit more predictable (in a backwards-compatible way). For example, Markdown.pl allows single quotes around a title in inline links, but not in reference links. This kind of difference is really hard for users to remember, so the spec allows single quotes in both contexts.

  • The rule for HTML blocks differs, though in most real cases it shouldn't make a difference. (See the section on HTML Blocks for details.) The spec's proposal makes it easy to include Markdown inside HTML block-level tags, if you want to, but also allows you to exclude this. It also makes parsing much easier, avoiding expensive backtracking.

  • It does not collapse adjacent bird-track blocks into a single blockquote:

    > this is two
    
    > blockquotes
    
    > this is a single
    >
    > blockquote with two paragraphs
    
  • Rules for content in lists differ in a few respects, though (as with HTML blocks), most lists in existing documents should render as intended. There is some discussion of the choice points and differences in the subsection of List Items entitled Motivation. We think that the spec's proposal does better than any existing implementation in rendering lists the way a human writer or reader would intuitively understand them. (We could give numerous examples of perfectly natural looking lists that nearly every existing implementation flubs up.)

  • Changing bullet characters, or changing from bullets to numbers or vice versa, starts a new list. We think that is almost always going to be the writer's intent.

  • The number that begins an ordered list item may be followed by either . or ). Changing the delimiter style starts a new list.

  • The start number of an ordered list is significant.

  • Fenced code blocks are supported, delimited by either backticks (```) or tildes (~~~).

Contributing

There is a forum for discussing CommonMark; you should use it instead of github issues for questions and possibly open-ended discussions. Use the github issue tracker only for simple, clear, actionable issues.

Authors

The spec was written by John MacFarlane, drawing on

  • his experience writing and maintaining Markdown implementations in several languages, including the first Markdown parser not based on regular expression substitutions (pandoc) and the first markdown parsers based on PEG grammars (peg-markdown, lunamark)
  • a detailed examination of the differences between existing Markdown implementations using BabelMark 2, and
  • extensive discussions with David Greenspan, Jeff Atwood, Vicent Marti, Neil Williams, and Benjamin Dumke-von der Ehe.

Since the first announcement, many people have contributed ideas. Kārlis Gaņģis was especially helpful in refining the rules for emphasis, strong emphasis, links, and images.

<h1>CommonMark</h1>
<p>CommonMark is a rationalized version of Markdown syntax,
with a <a href="http://spec.commonmark.org/">spec</a> and BSD-licensed reference
implementations in C and JavaScript.</p>
<p><a href="http://try.commonmark.org/">Try it now!</a></p>
<p>For more details, see <a href="http://commonmark.org">http://commonmark.org</a>.</p>
<p>This repository contains the spec itself, along with tools for
running tests against the spec, and for creating HTML and PDF versions
of the spec.</p>
<p>The reference implementations live in separate repositories:</p>
<ul>
<li>
<a href="https://github.com/commonmark/cmark">https://github.com/commonmark/cmark</a> (C)</li>
<li>
<a href="https://github.com/commonmark/commonmark.js">https://github.com/commonmark/commonmark.js</a> (JavaScript)</li>
</ul>
<p>There is a list of third-party libraries
in a dozen different languages
<a href="https://github.com/commonmark/CommonMark/wiki/List-of-CommonMark-Implementations">here</a>.</p>
<h2>Running tests against the spec</h2>
<p><a href="http://spec.commonmark.org/">The spec</a> contains over 500 embedded examples which serve as conformance
tests. To run the tests using an executable <code>$PROG</code>:</p>
<pre><code>python3 test/spec_tests.py --program $PROG
</code></pre>
<p>If you want to extract the raw test data from the spec without
actually running the tests, you can do:</p>
<pre><code>python3 test/spec_tests.py --dump-tests
</code></pre>
<p>and you'll get all the tests in JSON format.</p>
<h2>The spec</h2>
<p>The source of <a href="http://spec.commonmark.org/">the spec</a> is <code>spec.txt</code>.  This is basically a Markdown
file, with code examples written in a shorthand form:</p>
<pre><code>```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````
</code></pre>
<p>To build an HTML version of the spec, do <code>make spec.html</code>.  To build a
PDF version, do <code>make spec.pdf</code>.  For both versions, you must
have the lua rock <code>lcmark</code> installed:  after installing lua and
lua rocks, <code>luarocks install lcmark</code>.  For the PDF you must also
have xelatex installed.</p>
<p>The spec is written from the point of view of the human writer, not
the computer reader.  It is not an algorithm---an English translation of
a computer program---but a declarative description of what counts as a block
quote, a code block, and each of the other structural elements that can
make up a Markdown document.</p>
<p>Because John Gruber's <a href="http://daringfireball.net/projects/markdown/syntax">canonical syntax
description</a> leaves
many aspects of the syntax undetermined, writing a precise spec requires
making a large number of decisions, many of them somewhat arbitrary.
In making them, we have appealed to existing conventions and
considerations of simplicity, readability, expressive power, and
consistency.  We have tried to ensure that &quot;normal&quot; documents in the many
incompatible existing implementations of Markdown will render, as far as
possible, as their authors intended.  And we have tried to make the rules
for different elements work together harmoniously.  In places where
different decisions could have been made (for example, the rules
governing list indentation), we have explained the rationale for
our choices.  In a few cases, we have departed slightly from the canonical
syntax description, in ways that we think further the goals of Markdown
as stated in that description.</p>
<p>For the most part, we have limited ourselves to the basic elements
described in Gruber's canonical syntax description, eschewing extensions
like footnotes and definition lists.  It is important to get the core
right before considering such things. However, we have included a visible
syntax for line breaks and fenced code blocks.</p>
<h2>Differences from original Markdown</h2>
<p>There are only a few places where this spec says things that contradict
the canonical syntax description:</p>
<ul>
<li>
<p>It allows all punctuation symbols to be backslash-escaped,
not just the symbols with special meanings in Markdown. We found
that it was just too hard to remember which symbols could be
escaped.</p>
</li>
<li>
<p>It introduces an alternative syntax for hard line
breaks, a backslash at the end of the line, supplementing the
two-spaces-at-the-end-of-line rule. This is motivated by persistent
complaints about the “invisible” nature of the two-space rule.</p>
</li>
<li>
<p>Link syntax has been made a bit more predictable (in a
backwards-compatible way). For example, <code>Markdown.pl</code> allows single
quotes around a title in inline links, but not in reference links.
This kind of difference is really hard for users to remember, so the
spec allows single quotes in both contexts.</p>
</li>
<li>
<p>The rule for HTML blocks differs, though in most real cases it
shouldn't make a difference. (See the section on HTML Blocks
for details.) The spec's proposal makes it easy to include Markdown
inside HTML block-level tags, if you want to, but also allows you to
exclude this. It also makes parsing much easier, avoiding
expensive backtracking.</p>
</li>
<li>
<p>It does not collapse adjacent bird-track blocks into a single
blockquote:</p>
<pre><code>&gt; this is two

&gt; blockquotes

&gt; this is a single
&gt;
&gt; blockquote with two paragraphs
</code></pre>
</li>
<li>
<p>Rules for content in lists differ in a few respects, though (as with
HTML blocks), most lists in existing documents should render as
intended. There is some discussion of the choice points and
differences in the subsection of List Items entitled Motivation.
We think that the spec's proposal does better than any existing
implementation in rendering lists the way a human writer or reader
would intuitively understand them. (We could give numerous examples
of perfectly natural looking lists that nearly every existing
implementation flubs up.)</p>
</li>
<li>
<p>Changing bullet characters, or changing from bullets to numbers or
vice versa, starts a new list. We think that is almost always going
to be the writer's intent.</p>
</li>
<li>
<p>The number that begins an ordered list item may be followed by
either <code>.</code> or <code>)</code>. Changing the delimiter style starts a new
list.</p>
</li>
<li>
<p>The start number of an ordered list is significant.</p>
</li>
<li>
<p>Fenced code blocks are supported, delimited by either
backticks (<code>```</code>) or tildes (<code>~~~</code>).</p>
</li>
</ul>
<h2>Contributing</h2>
<p>There is a <a href="http://talk.commonmark.org">forum for discussing
CommonMark</a>; you should use it instead of
github issues for questions and possibly open-ended discussions.
Use the <a href="http://github.com/commonmark/CommonMark/issues">github issue tracker</a>
only for simple, clear, actionable issues.</p>
<h2>Authors</h2>
<p>The spec was written by John MacFarlane, drawing on</p>
<ul>
<li>his experience writing and maintaining Markdown implementations in several
languages, including the first Markdown parser not based on regular
expression substitutions (<a href="http://github.com/jgm/pandoc">pandoc</a>) and
the first markdown parsers based on PEG grammars
(<a href="http://github.com/jgm/peg-markdown">peg-markdown</a>,
<a href="http://github.com/jgm/lunamark">lunamark</a>)</li>
<li>a detailed examination of the differences between existing Markdown
implementations using <a href="http://johnmacfarlane.net/babelmark2/">BabelMark 2</a>,
and</li>
<li>extensive discussions with David Greenspan, Jeff Atwood, Vicent
Marti, Neil Williams, and Benjamin Dumke-von der Ehe.</li>
</ul>
<p>Since the first announcement, many people have contributed ideas.
Kārlis Gaņģis was especially helpful in refining the rules for
emphasis, strong emphasis, links, and images.</p>

CommonMark

CommonMark is a rationalized version of Markdown syntax, with a spec and BSD-licensed reference implementations in C and JavaScript.

Try it now!

For more details, see http://commonmark.org.

This repository contains the spec itself, along with tools for running tests against the spec, and for creating HTML and PDF versions of the spec.

The reference implementations live in separate repositories:

There is a list of third-party libraries in a dozen different languages here.

Running tests against the spec

The spec contains over 500 embedded examples which serve as conformance tests. To run the tests using an executable $PROG:

python3 test/spec_tests.py --program $PROG

If you want to extract the raw test data from the spec without actually running the tests, you can do:

python3 test/spec_tests.py --dump-tests

and you'll get all the tests in JSON format.

The spec

The source of the spec is spec.txt. This is basically a Markdown file, with code examples written in a shorthand form:

```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````

To build an HTML version of the spec, do make spec.html. To build a PDF version, do make spec.pdf. For both versions, you must have the lua rock lcmark installed: after installing lua and lua rocks, luarocks install lcmark. For the PDF you must also have xelatex installed.

The spec is written from the point of view of the human writer, not the computer reader. It is not an algorithm---an English translation of a computer program---but a declarative description of what counts as a block quote, a code block, and each of the other structural elements that can make up a Markdown document.

Because John Gruber's canonical syntax description leaves many aspects of the syntax undetermined, writing a precise spec requires making a large number of decisions, many of them somewhat arbitrary. In making them, we have appealed to existing conventions and considerations of simplicity, readability, expressive power, and consistency. We have tried to ensure that "normal" documents in the many incompatible existing implementations of Markdown will render, as far as possible, as their authors intended. And we have tried to make the rules for different elements work together harmoniously. In places where different decisions could have been made (for example, the rules governing list indentation), we have explained the rationale for our choices. In a few cases, we have departed slightly from the canonical syntax description, in ways that we think further the goals of Markdown as stated in that description.

For the most part, we have limited ourselves to the basic elements described in Gruber's canonical syntax description, eschewing extensions like footnotes and definition lists. It is important to get the core right before considering such things. However, we have included a visible syntax for line breaks and fenced code blocks.

Differences from original Markdown

There are only a few places where this spec says things that contradict the canonical syntax description:

  • It allows all punctuation symbols to be backslash-escaped, not just the symbols with special meanings in Markdown. We found that it was just too hard to remember which symbols could be escaped.

  • It introduces an alternative syntax for hard line breaks, a backslash at the end of the line, supplementing the two-spaces-at-the-end-of-line rule. This is motivated by persistent complaints about the “invisible” nature of the two-space rule.

  • Link syntax has been made a bit more predictable (in a backwards-compatible way). For example, Markdown.pl allows single quotes around a title in inline links, but not in reference links. This kind of difference is really hard for users to remember, so the spec allows single quotes in both contexts.

  • The rule for HTML blocks differs, though in most real cases it shouldn't make a difference. (See the section on HTML Blocks for details.) The spec's proposal makes it easy to include Markdown inside HTML block-level tags, if you want to, but also allows you to exclude this. It also makes parsing much easier, avoiding expensive backtracking.

  • It does not collapse adjacent bird-track blocks into a single blockquote:

    > this is two
    
    > blockquotes
    
    > this is a single
    >
    > blockquote with two paragraphs
    
  • Rules for content in lists differ in a few respects, though (as with HTML blocks), most lists in existing documents should render as intended. There is some discussion of the choice points and differences in the subsection of List Items entitled Motivation. We think that the spec's proposal does better than any existing implementation in rendering lists the way a human writer or reader would intuitively understand them. (We could give numerous examples of perfectly natural looking lists that nearly every existing implementation flubs up.)

  • Changing bullet characters, or changing from bullets to numbers or vice versa, starts a new list. We think that is almost always going to be the writer's intent.

  • The number that begins an ordered list item may be followed by either . or ). Changing the delimiter style starts a new list.

  • The start number of an ordered list is significant.

  • Fenced code blocks are supported, delimited by either backticks (```) or tildes (~~~).

Contributing

There is a forum for discussing CommonMark; you should use it instead of github issues for questions and possibly open-ended discussions. Use the github issue tracker only for simple, clear, actionable issues.

Authors

The spec was written by John MacFarlane, drawing on

  • his experience writing and maintaining Markdown implementations in several languages, including the first Markdown parser not based on regular expression substitutions (pandoc) and the first markdown parsers based on PEG grammars (peg-markdown, lunamark)
  • a detailed examination of the differences between existing Markdown implementations using BabelMark 2, and
  • extensive discussions with David Greenspan, Jeff Atwood, Vicent Marti, Neil Williams, and Benjamin Dumke-von der Ehe.

Since the first announcement, many people have contributed ideas. Kārlis Gaņģis was especially helpful in refining the rules for emphasis, strong emphasis, links, and images.

<h1>CommonMark</h1>
<p>CommonMark is a rationalized version of Markdown syntax,
with a <a href="http://spec.commonmark.org/">spec</a> and BSD-licensed reference
implementations in C and JavaScript.</p>
<p><a href="http://try.commonmark.org/">Try it now!</a></p>
<p>For more details, see <a href="http://commonmark.org">http://commonmark.org</a>.</p>
<p>This repository contains the spec itself, along with tools for
running tests against the spec, and for creating HTML and PDF versions
of the spec.</p>
<p>The reference implementations live in separate repositories:</p>
<ul>
<li><a href="https://github.com/commonmark/cmark">https://github.com/commonmark/cmark</a> (C)</li>
<li><a href="https://github.com/commonmark/commonmark.js">https://github.com/commonmark/commonmark.js</a> (JavaScript)</li>
</ul>
<p>There is a list of third-party libraries
in a dozen different languages
<a href="https://github.com/commonmark/CommonMark/wiki/List-of-CommonMark-Implementations">here</a>.</p>
<h2>Running tests against the spec</h2>
<p><a href="http://spec.commonmark.org/">The spec</a> contains over 500 embedded examples which serve as conformance
tests. To run the tests using an executable <code>$PROG</code>:</p>
<pre><code>python3 test/spec_tests.py --program $PROG</code></pre>
<p>If you want to extract the raw test data from the spec without
actually running the tests, you can do:</p>
<pre><code>python3 test/spec_tests.py --dump-tests</code></pre>
<p>and you'll get all the tests in JSON format.</p>
<h2>The spec</h2>
<p>The source of <a href="http://spec.commonmark.org/">the spec</a> is <code>spec.txt</code>.  This is basically a Markdown
file, with code examples written in a shorthand form:</p>
<pre><code>```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````</code></pre>
<p>To build an HTML version of the spec, do <code>make spec.html</code>.  To build a
PDF version, do <code>make spec.pdf</code>.  For both versions, you must
have the lua rock <code>lcmark</code> installed:  after installing lua and
lua rocks, <code>luarocks install lcmark</code>.  For the PDF you must also
have xelatex installed.</p>
<p>The spec is written from the point of view of the human writer, not
the computer reader.  It is not an algorithm---an English translation of
a computer program---but a declarative description of what counts as a block
quote, a code block, and each of the other structural elements that can
make up a Markdown document.</p>
<p>Because John Gruber's <a href="http://daringfireball.net/projects/markdown/syntax">canonical syntax
description</a> leaves
many aspects of the syntax undetermined, writing a precise spec requires
making a large number of decisions, many of them somewhat arbitrary.
In making them, we have appealed to existing conventions and
considerations of simplicity, readability, expressive power, and
consistency.  We have tried to ensure that &quot;normal&quot; documents in the many
incompatible existing implementations of Markdown will render, as far as
possible, as their authors intended.  And we have tried to make the rules
for different elements work together harmoniously.  In places where
different decisions could have been made (for example, the rules
governing list indentation), we have explained the rationale for
our choices.  In a few cases, we have departed slightly from the canonical
syntax description, in ways that we think further the goals of Markdown
as stated in that description.</p>
<p>For the most part, we have limited ourselves to the basic elements
described in Gruber's canonical syntax description, eschewing extensions
like footnotes and definition lists.  It is important to get the core
right before considering such things. However, we have included a visible
syntax for line breaks and fenced code blocks.</p>
<h2>Differences from original Markdown</h2>
<p>There are only a few places where this spec says things that contradict
the canonical syntax description:</p>
<ul>
<li>
<p>It allows all punctuation symbols to be backslash-escaped,
not just the symbols with special meanings in Markdown. We found
that it was just too hard to remember which symbols could be
escaped.</p>
</li>
<li>
<p>It introduces an alternative syntax for hard line
breaks, a backslash at the end of the line, supplementing the
two-spaces-at-the-end-of-line rule. This is motivated by persistent
complaints about the “invisible” nature of the two-space rule.</p>
</li>
<li>
<p>Link syntax has been made a bit more predictable (in a
backwards-compatible way). For example, <code>Markdown.pl</code> allows single
quotes around a title in inline links, but not in reference links.
This kind of difference is really hard for users to remember, so the
spec allows single quotes in both contexts.</p>
</li>
<li>
<p>The rule for HTML blocks differs, though in most real cases it
shouldn't make a difference. (See the section on HTML Blocks
for details.) The spec's proposal makes it easy to include Markdown
inside HTML block-level tags, if you want to, but also allows you to
exclude this. It also makes parsing much easier, avoiding
expensive backtracking.</p>
</li>
<li>
<p>It does not collapse adjacent bird-track blocks into a single
blockquote:</p>
<pre><code>&gt; this is two

&gt; blockquotes

&gt; this is a single
&gt;
&gt; blockquote with two paragraphs</code></pre>
</li>
<li>
<p>Rules for content in lists differ in a few respects, though (as with
HTML blocks), most lists in existing documents should render as
intended. There is some discussion of the choice points and
differences in the subsection of List Items entitled Motivation.
We think that the spec's proposal does better than any existing
implementation in rendering lists the way a human writer or reader
would intuitively understand them. (We could give numerous examples
of perfectly natural looking lists that nearly every existing
implementation flubs up.)</p>
</li>
<li>
<p>Changing bullet characters, or changing from bullets to numbers or
vice versa, starts a new list. We think that is almost always going
to be the writer's intent.</p>
</li>
<li>
<p>The number that begins an ordered list item may be followed by
either <code>.</code> or <code>)</code>. Changing the delimiter style starts a new
list.</p>
</li>
<li>
<p>The start number of an ordered list is significant.</p>
</li>
<li>
<p>Fenced code blocks are supported, delimited by either
backticks (<code>```</code>) or tildes (<code>~~~</code>).</p>
</li>
</ul>
<h2>Contributing</h2>
<p>There is a <a href="http://talk.commonmark.org">forum for discussing
CommonMark</a>; you should use it instead of
github issues for questions and possibly open-ended discussions.
Use the <a href="http://github.com/commonmark/CommonMark/issues">github issue tracker</a>
only for simple, clear, actionable issues.</p>
<h2>Authors</h2>
<p>The spec was written by John MacFarlane, drawing on</p>
<ul>
<li>his experience writing and maintaining Markdown implementations in several
languages, including the first Markdown parser not based on regular
expression substitutions (<a href="http://github.com/jgm/pandoc">pandoc</a>) and
the first markdown parsers based on PEG grammars
(<a href="http://github.com/jgm/peg-markdown">peg-markdown</a>,
<a href="http://github.com/jgm/lunamark">lunamark</a>)</li>
<li>a detailed examination of the differences between existing Markdown
implementations using <a href="http://johnmacfarlane.net/babelmark2/">BabelMark 2</a>,
and</li>
<li>extensive discussions with David Greenspan, Jeff Atwood, Vicent
Marti, Neil Williams, and Benjamin Dumke-von der Ehe.</li>
</ul>
<p>Since the first announcement, many people have contributed ideas.
Kārlis Gaņģis was especially helpful in refining the rules for
emphasis, strong emphasis, links, and images.</p>

CommonMark

CommonMark is a rationalized version of Markdown syntax, with a spec and BSD-licensed reference implementations in C and JavaScript.

Try it now!

For more details, see http://commonmark.org.

This repository contains the spec itself, along with tools for running tests against the spec, and for creating HTML and PDF versions of the spec.

The reference implementations live in separate repositories:

There is a list of third-party libraries in a dozen different languages here.

Running tests against the spec

The spec contains over 500 embedded examples which serve as conformance tests. To run the tests using an executable $PROG:

python3 test/spec_tests.py --program $PROG

If you want to extract the raw test data from the spec without actually running the tests, you can do:

python3 test/spec_tests.py --dump-tests

and you'll get all the tests in JSON format.

The spec

The source of the spec is spec.txt. This is basically a Markdown file, with code examples written in a shorthand form:

```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````

To build an HTML version of the spec, do make spec.html. To build a PDF version, do make spec.pdf. For both versions, you must have the lua rock lcmark installed: after installing lua and lua rocks, luarocks install lcmark. For the PDF you must also have xelatex installed.

The spec is written from the point of view of the human writer, not the computer reader. It is not an algorithm---an English translation of a computer program---but a declarative description of what counts as a block quote, a code block, and each of the other structural elements that can make up a Markdown document.

Because John Gruber's canonical syntax description leaves many aspects of the syntax undetermined, writing a precise spec requires making a large number of decisions, many of them somewhat arbitrary. In making them, we have appealed to existing conventions and considerations of simplicity, readability, expressive power, and consistency. We have tried to ensure that "normal" documents in the many incompatible existing implementations of Markdown will render, as far as possible, as their authors intended. And we have tried to make the rules for different elements work together harmoniously. In places where different decisions could have been made (for example, the rules governing list indentation), we have explained the rationale for our choices. In a few cases, we have departed slightly from the canonical syntax description, in ways that we think further the goals of Markdown as stated in that description.

For the most part, we have limited ourselves to the basic elements described in Gruber's canonical syntax description, eschewing extensions like footnotes and definition lists. It is important to get the core right before considering such things. However, we have included a visible syntax for line breaks and fenced code blocks.

Differences from original Markdown

There are only a few places where this spec says things that contradict the canonical syntax description:

  • It allows all punctuation symbols to be backslash-escaped, not just the symbols with special meanings in Markdown. We found that it was just too hard to remember which symbols could be escaped.

  • It introduces an alternative syntax for hard line breaks, a backslash at the end of the line, supplementing the two-spaces-at-the-end-of-line rule. This is motivated by persistent complaints about the “invisible” nature of the two-space rule.

  • Link syntax has been made a bit more predictable (in a backwards-compatible way). For example, Markdown.pl allows single quotes around a title in inline links, but not in reference links. This kind of difference is really hard for users to remember, so the spec allows single quotes in both contexts.

  • The rule for HTML blocks differs, though in most real cases it shouldn't make a difference. (See the section on HTML Blocks for details.) The spec's proposal makes it easy to include Markdown inside HTML block-level tags, if you want to, but also allows you to exclude this. It also makes parsing much easier, avoiding expensive backtracking.

  • It does not collapse adjacent bird-track blocks into a single blockquote:

    > this is two
    
    > blockquotes
    
    > this is a single
    >
    > blockquote with two paragraphs
  • Rules for content in lists differ in a few respects, though (as with HTML blocks), most lists in existing documents should render as intended. There is some discussion of the choice points and differences in the subsection of List Items entitled Motivation. We think that the spec's proposal does better than any existing implementation in rendering lists the way a human writer or reader would intuitively understand them. (We could give numerous examples of perfectly natural looking lists that nearly every existing implementation flubs up.)

  • Changing bullet characters, or changing from bullets to numbers or vice versa, starts a new list. We think that is almost always going to be the writer's intent.

  • The number that begins an ordered list item may be followed by either . or ). Changing the delimiter style starts a new list.

  • The start number of an ordered list is significant.

  • Fenced code blocks are supported, delimited by either backticks (```) or tildes (~~~).

Contributing

There is a forum for discussing CommonMark; you should use it instead of github issues for questions and possibly open-ended discussions. Use the github issue tracker only for simple, clear, actionable issues.

Authors

The spec was written by John MacFarlane, drawing on

  • his experience writing and maintaining Markdown implementations in several languages, including the first Markdown parser not based on regular expression substitutions (pandoc) and the first markdown parsers based on PEG grammars (peg-markdown, lunamark)
  • a detailed examination of the differences between existing Markdown implementations using BabelMark 2, and
  • extensive discussions with David Greenspan, Jeff Atwood, Vicent Marti, Neil Williams, and Benjamin Dumke-von der Ehe.

Since the first announcement, many people have contributed ideas. Kārlis Gaņģis was especially helpful in refining the rules for emphasis, strong emphasis, links, and images.

<h1>CommonMark</h1>

<p>CommonMark is a rationalized version of Markdown syntax,
with a <a href="http://spec.commonmark.org/">spec</a> and BSD-licensed reference
implementations in C and JavaScript.</p>

<p><a href="http://try.commonmark.org/">Try it now!</a></p>

<p>For more details, see <a href="http://commonmark.org">http://commonmark.org</a>.</p>

<p>This repository contains the spec itself, along with tools for
running tests against the spec, and for creating HTML and PDF versions
of the spec.</p>

<p>The reference implementations live in separate repositories:</p>

<ul>
<li><a href="https://github.com/commonmark/cmark">https://github.com/commonmark/cmark</a> (C)</li>
<li><a href="https://github.com/commonmark/commonmark.js">https://github.com/commonmark/commonmark.js</a> (JavaScript)</li>
</ul>

<p>There is a list of third-party libraries
in a dozen different languages
<a href="https://github.com/commonmark/CommonMark/wiki/List-of-CommonMark-Implementations">here</a>.</p>

<h2>Running tests against the spec</h2>

<p><a href="http://spec.commonmark.org/">The spec</a> contains over 500 embedded examples which serve as conformance
tests. To run the tests using an executable <code>$PROG</code>:</p>

<pre><code>python3 test/spec_tests.py --program $PROG
</code></pre>

<p>If you want to extract the raw test data from the spec without
actually running the tests, you can do:</p>

<pre><code>python3 test/spec_tests.py --dump-tests
</code></pre>

<p>and you'll get all the tests in JSON format.</p>

<h2>The spec</h2>

<p>The source of <a href="http://spec.commonmark.org/">the spec</a> is <code>spec.txt</code>.  This is basically a Markdown
file, with code examples written in a shorthand form:</p>

<pre><code>```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````
</code></pre>

<p>To build an HTML version of the spec, do <code>make spec.html</code>.  To build a
PDF version, do <code>make spec.pdf</code>.  For both versions, you must
have the lua rock <code>lcmark</code> installed:  after installing lua and
lua rocks, <code>luarocks install lcmark</code>.  For the PDF you must also
have xelatex installed.</p>

<p>The spec is written from the point of view of the human writer, not
the computer reader.  It is not an algorithm---an English translation of
a computer program---but a declarative description of what counts as a block
quote, a code block, and each of the other structural elements that can
make up a Markdown document.</p>

<p>Because John Gruber's <a href="http://daringfireball.net/projects/markdown/syntax">canonical syntax
description</a> leaves
many aspects of the syntax undetermined, writing a precise spec requires
making a large number of decisions, many of them somewhat arbitrary.
In making them, we have appealed to existing conventions and
considerations of simplicity, readability, expressive power, and
consistency.  We have tried to ensure that "normal" documents in the many
incompatible existing implementations of Markdown will render, as far as
possible, as their authors intended.  And we have tried to make the rules
for different elements work together harmoniously.  In places where
different decisions could have been made (for example, the rules
governing list indentation), we have explained the rationale for
our choices.  In a few cases, we have departed slightly from the canonical
syntax description, in ways that we think further the goals of Markdown
as stated in that description.</p>

<p>For the most part, we have limited ourselves to the basic elements
described in Gruber's canonical syntax description, eschewing extensions
like footnotes and definition lists.  It is important to get the core
right before considering such things. However, we have included a visible
syntax for line breaks and fenced code blocks.</p>

<h2>Differences from original Markdown</h2>

<p>There are only a few places where this spec says things that contradict
the canonical syntax description:</p>

<ul>
<li><p>It allows all punctuation symbols to be backslash-escaped,
not just the symbols with special meanings in Markdown. We found
that it was just too hard to remember which symbols could be
escaped.</p></li>
<li><p>It introduces an alternative syntax for hard line
breaks, a backslash at the end of the line, supplementing the
two-spaces-at-the-end-of-line rule. This is motivated by persistent
complaints about the “invisible” nature of the two-space rule.</p></li>
<li><p>Link syntax has been made a bit more predictable (in a
backwards-compatible way). For example, <code>Markdown.pl</code> allows single
quotes around a title in inline links, but not in reference links.
This kind of difference is really hard for users to remember, so the
spec allows single quotes in both contexts.</p></li>
<li><p>The rule for HTML blocks differs, though in most real cases it
shouldn't make a difference. (See the section on HTML Blocks
for details.) The spec's proposal makes it easy to include Markdown
inside HTML block-level tags, if you want to, but also allows you to
exclude this. It also makes parsing much easier, avoiding
expensive backtracking.</p></li>
<li><p>It does not collapse adjacent bird-track blocks into a single
blockquote:</p>

<pre><code>&gt; this is two

&gt; blockquotes

&gt; this is a single
&gt;
&gt; blockquote with two paragraphs
</code></pre></li>
<li><p>Rules for content in lists differ in a few respects, though (as with
HTML blocks), most lists in existing documents should render as
intended. There is some discussion of the choice points and
differences in the subsection of List Items entitled Motivation.
We think that the spec's proposal does better than any existing
implementation in rendering lists the way a human writer or reader
would intuitively understand them. (We could give numerous examples
of perfectly natural looking lists that nearly every existing
implementation flubs up.)</p></li>
<li><p>Changing bullet characters, or changing from bullets to numbers or
vice versa, starts a new list. We think that is almost always going
to be the writer's intent.</p></li>
<li><p>The number that begins an ordered list item may be followed by
either <code>.</code> or <code>)</code>. Changing the delimiter style starts a new
list.</p></li>
<li><p>The start number of an ordered list is significant.</p></li>
<li><p>Fenced code blocks are supported, delimited by either
backticks (<code>```</code>) or tildes (<code>~~~</code>).</p></li>
</ul>

<h2>Contributing</h2>

<p>There is a <a href="http://talk.commonmark.org">forum for discussing
CommonMark</a>; you should use it instead of
github issues for questions and possibly open-ended discussions.
Use the <a href="http://github.com/commonmark/CommonMark/issues">github issue tracker</a>
only for simple, clear, actionable issues.</p>

<h2>Authors</h2>

<p>The spec was written by John MacFarlane, drawing on</p>

<ul>
<li>his experience writing and maintaining Markdown implementations in several
languages, including the first Markdown parser not based on regular
expression substitutions (<a href="http://github.com/jgm/pandoc">pandoc</a>) and
the first markdown parsers based on PEG grammars
(<a href="http://github.com/jgm/peg-markdown">peg-markdown</a>,
<a href="http://github.com/jgm/lunamark">lunamark</a>)</li>
<li>a detailed examination of the differences between existing Markdown
implementations using <a href="http://johnmacfarlane.net/babelmark2/">BabelMark 2</a>,
and</li>
<li>extensive discussions with David Greenspan, Jeff Atwood, Vicent
Marti, Neil Williams, and Benjamin Dumke-von der Ehe.</li>
</ul>

<p>Since the first announcement, many people have contributed ideas.
Kārlis Gaņģis was especially helpful in refining the rules for
emphasis, strong emphasis, links, and images.</p>

CommonMark

CommonMark is a rationalized version of Markdown syntax, with a spec and BSD-licensed reference implementations in C and JavaScript.

Try it now!

For more details, see http://commonmark.org.

This repository contains the spec itself, along with tools for running tests against the spec, and for creating HTML and PDF versions of the spec.

The reference implementations live in separate repositories:

There is a list of third-party libraries in a dozen different languages here.

Running tests against the spec

The spec contains over 500 embedded examples which serve as conformance tests. To run the tests using an executable $PROG:

python3 test/spec_tests.py --program $PROG

If you want to extract the raw test data from the spec without actually running the tests, you can do:

python3 test/spec_tests.py --dump-tests

and you'll get all the tests in JSON format.

The spec

The source of the spec is spec.txt. This is basically a Markdown file, with code examples written in a shorthand form:

```````````````````````````````` example
Markdown source
.
expected HTML output
````````````````````````````````

To build an HTML version of the spec, do make spec.html. To build a PDF version, do make spec.pdf. For both versions, you must have the lua rock lcmark installed: after installing lua and lua rocks, luarocks install lcmark. For the PDF you must also have xelatex installed.

The spec is written from the point of view of the human writer, not the computer reader. It is not an algorithm---an English translation of a computer program---but a declarative description of what counts as a block quote, a code block, and each of the other structural elements that can make up a Markdown document.

Because John Gruber's canonical syntax description leaves many aspects of the syntax undetermined, writing a precise spec requires making a large number of decisions, many of them somewhat arbitrary. In making them, we have appealed to existing conventions and considerations of simplicity, readability, expressive power, and consistency. We have tried to ensure that "normal" documents in the many incompatible existing implementations of Markdown will render, as far as possible, as their authors intended. And we have tried to make the rules for different elements work together harmoniously. In places where different decisions could have been made (for example, the rules governing list indentation), we have explained the rationale for our choices. In a few cases, we have departed slightly from the canonical syntax description, in ways that we think further the goals of Markdown as stated in that description.

For the most part, we have limited ourselves to the basic elements described in Gruber's canonical syntax description, eschewing extensions like footnotes and definition lists. It is important to get the core right before considering such things. However, we have included a visible syntax for line breaks and fenced code blocks.

Differences from original Markdown

There are only a few places where this spec says things that contradict the canonical syntax description:

  • It allows all punctuation symbols to be backslash-escaped, not just the symbols with special meanings in Markdown. We found that it was just too hard to remember which symbols could be escaped.

  • It introduces an alternative syntax for hard line breaks, a backslash at the end of the line, supplementing the two-spaces-at-the-end-of-line rule. This is motivated by persistent complaints about the “invisible” nature of the two-space rule.

  • Link syntax has been made a bit more predictable (in a backwards-compatible way). For example, Markdown.pl allows single quotes around a title in inline links, but not in reference links. This kind of difference is really hard for users to remember, so the spec allows single quotes in both contexts.

  • The rule for HTML blocks differs, though in most real cases it shouldn't make a difference. (See the section on HTML Blocks for details.) The spec's proposal makes it easy to include Markdown inside HTML block-level tags, if you want to, but also allows you to exclude this. It also makes parsing much easier, avoiding expensive backtracking.

  • It does not collapse adjacent bird-track blocks into a single blockquote:

    > this is two
    
    > blockquotes
    
    > this is a single
    >
    > blockquote with two paragraphs
    
  • Rules for content in lists differ in a few respects, though (as with HTML blocks), most lists in existing documents should render as intended. There is some discussion of the choice points and differences in the subsection of List Items entitled Motivation. We think that the spec's proposal does better than any existing implementation in rendering lists the way a human writer or reader would intuitively understand them. (We could give numerous examples of perfectly natural looking lists that nearly every existing implementation flubs up.)

  • Changing bullet characters, or changing from bullets to numbers or vice versa, starts a new list. We think that is almost always going to be the writer's intent.

  • The number that begins an ordered list item may be followed by either . or ). Changing the delimiter style starts a new list.

  • The start number of an ordered list is significant.

  • Fenced code blocks are supported, delimited by either backticks (```) or tildes (~~~).

Contributing

There is a forum for discussing CommonMark; you should use it instead of github issues for questions and possibly open-ended discussions. Use the github issue tracker only for simple, clear, actionable issues.

Authors

The spec was written by John MacFarlane, drawing on

  • his experience writing and maintaining Markdown implementations in several languages, including the first Markdown parser not based on regular expression substitutions (pandoc) and the first markdown parsers based on PEG grammars (peg-markdown, lunamark)
  • a detailed examination of the differences between existing Markdown implementations using BabelMark 2, and
  • extensive discussions with David Greenspan, Jeff Atwood, Vicent Marti, Neil Williams, and Benjamin Dumke-von der Ehe.

Since the first announcement, many people have contributed ideas. Kārlis Gaņģis was especially helpful in refining the rules for emphasis, strong emphasis, links, and images.