deft md to-html

CommonMark
==========

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

[Try it now!](https://spec.commonmark.org/dingus/)

[the spec]:  https://spec.commonmark.org/

For more details, see <https://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:

- <https://github.com/commonmark/cmark> (C)
- <https://github.com/commonmark/commonmark.js> (JavaScript)

There is a list of third-party libraries
in a dozen different languages
[here](https://github.com/commonmark/CommonMark/wiki/List-of-CommonMark-Implementations).

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.

JavaScript developers may find it more convenient to use the
[`commonmark-spec` npm package], which is published from this
repository.  It exports an array `tests` of JSON objects with
the format

```json
{
  "markdown": "Foo\nBar\n---\n",
  "html": "<h2>Foo\nBar</h2>\n",
  "section": "Setext headings",
  "number": 65
}
```

[`commonmark-spec` npm package]: https://www.npmjs.com/package/commonmark-spec

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](https://daringfireball.net/projects/markdown/syntax) 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 imple
… 4664 more characters

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>CommonMark</title>
<style>body{max-width:46rem;margin:2rem auto;padding:0 1rem;font:16px/1.6 -apple-system,'Segoe UI',Roboto,'PingFang SC','Noto Sans CJK SC',sans-serif;color:#1f2328}pre{background:#f6f8fa;padding:.8rem;overflow:auto;border-radius:6px}code{font:.9em ui-monospace,Menlo,Consolas,monospace}table{border-collapse:collapse}th,td{border:1px solid #d0d7de;padding:.3rem .6rem}blockquote{margin:0;padding:0 1rem;color:#59636e;border-left:.25rem solid #d0d7de}img{max-width:100%}</style>
</head>
<body>
<h1 id="commonmark">CommonMark</h1>
<p>CommonMark is a rationalized version of Markdown syntax,
with a <a href="https://spec.commonmark.org/">spec</a> and BSD-licensed reference
implementations in C and JavaScript.</p>
<p><a href="https://spec.commonmark.org/dingus/">Try it now!</a></p>
<p>For more details, see <a href="https://commonmark.org">https://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 id="running-tests-against-the-spec">Running tests against the spec</h2>
<p><a href="https://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>
<p>JavaScript developers may find it more convenient to use the
<a href="https://www.npmjs.com/package/commonmark-spec"><code>commonmark-spec</code> npm package</a>, which is published from this
repository.  It exports an array <code>tests</code> of JSON objects with
the format</p>
<pre><code class="language-json">{
  "markdown": "Foo\nBar\n---\n",
  "html": "&lt;h2&gt;Foo\nBar&lt;/h2&gt;\n",
  "section": "Setext headings",
  "number": 65
}
</code></pre>
<h2 id="the-spec">The spec</h2>
<p>The source of <a href="https://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
````````````````````````
… 6085 more characters