CommonMark

CommonMarkはマークダウンの構文の合理化された版であり、仕様とBSDの使用許諾が付されているCとJavaScriptでの参照実装を備えています。

今すぐ試してみよう！

詳しくは https://commonmark.org をご参照ください。

本リポジトリには仕様そのものとともに、仕様に対してテストを実行したり、仕様のHTML版およびPDF版を作ったりするためのツールが含まれています。

参照実装は別のリポジトリにあります。

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

多種多様な言語によるサードパーティのライブラリの一覧がこちらにあります。

仕様書に沿っているかテストする

仕様には500を越す埋め込まれた例が含まれており適合性試験として供されます。実行プログラム$PROGを使ってテストを実行するには以下とします。

python3 test/spec_tests.py --program $PROG

実際にテストを実行することなく仕様から素のテストデータを抽出したければ、次のようにできます。

python3 test/spec_tests.py --dump-tests

こうするとすべてのテストをJSON形式で得られます。

JavaScriptで開発している方はcommonmark-spec npmパッケージを使うとより便利に思われるかもしれません。このリポジトリから公開されています。次の形式のJSONオブジェクトの配列testsをエクスポートするものです。

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

仕様について

仕様のソースはspec.txtです。これは基本的にはマークダウンファイルであって、略記の形式で書かれたコードの例があります。

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

仕様のHTML版を作るには、make spec.htmlとしてください。 PDF版を作るには、make spec.pdfとしてください。どちらの版のためにも、lua rockのlcmarkがインストールされていなければなりません。つまりluaとlua rocksをインストールした後に、luarocks install lcmarkとします。 PDFについてはxelatexもインストールされていなければなりません。

仕様は人間の書き手の視点から書かれており、コンピューターの読み手ではありません。アルゴリズム――すなわちコンピュータプログラムの和訳――ではなく何をもってブロック引用や、コードブロックや、マークダウン文書を作り上げることのできるその他の構造的な各要素とするかの宣言的な説明です。

John Gruber氏の正典的な構文の説明には未決定な多くの側面が残されているため、精確な仕様を書く上で数多の決定を下すことが要求されており、その多くはどこかしら独断的です。そうした決定を下す中で、既存の慣習と簡潔性、可読性、表現力、一貫性への配慮を希求してきました。多くの互換性のない既存のマークダウンの実装による「普通」の文書が、可能な限りに、それらの執筆者が意図した通りに呈示されることを確かなものにしようとしてきました。そして様々な要素が協調的に働くような規則を作ろうとしてきました。異なる決定を下すことができたであろうところでは（例えば、リストの字下げを統制する規則）、そこでの選択についての原則を説明しました。二三の場合においては、正典的な構文の説明からわずかに外しましたが、その説明で述べられているマークダウンの目標を見越した上でのものです。

ほとんどの部分で、Gruber氏の正典的な構文の説明で記述されている基礎的な要素に留め、脚註や定義リストのような拡張は控えました。そうしたものを検討する前に中枢をしっかりしたものにすることが重要なのです。しかしながら、ここでは改行と有塀コードブロックのための可視化された構文を加えました。

元来のマークダウンとの違い

本仕様で正典的な構文の説明と矛盾することを述べているところがごく数点あります。

すべての約物の記号をバックスラッシュでエスケープすることを許容しており、マークダウンにおいて特別な意味を持つ記号だけではありません。どの記号がエスケープされることがあるのか覚えることはただただ大変にすぎるとわかったためです。
固い改行のための代替の構文、すなわち行の終わりのバックスラッシュを導入し、行の終わりの2つの空白の規則を補完しています。これは2つの空白の規則の「不可視」な性質についての根強い不満の声を動機としています。
リンクの構文は（後方互換な形で）少しだけ予測できるものになりました。例えば、Markdown.plでは行内リンク中の題の周りに単一引用符を許容していますが、参照リンクではされていません。こうした類の違いは利用者にとって実に覚えづらいため、仕様では両方の文脈で単一引用符を許容しています。
ほとんどの実際の場合では違いはないはずとはいえ、HTMLブロックのための規則が違っています（詳細はHTMLブロックの節を参照）。仕様の提案内容では、そうしたい場合に、HTMLのブロック水準のタグ内にマークダウンを含めやすくしていますが、この働きを除くことも許容しています。ずっと構文解析しやすくなり、高くつく後戻りの解析を避けています。
隣合う鳥趾付きのブロックを単一のブロック引用に縮めません（訳註：原文では「鳥趾付き」は "bird-track" となっており、このうちの "bird" は文芸的Haskellにおける "Bird style" を兼ねた造語と思われます。ここで "Bird" はHaskellの設計に携わったRichard Bird氏に由来します）。
```
> these are two

> blockquotes

> this is a single
>
> blockquote with two paragraphs
```
（HTMLブロックと同じく）既存の文書中のほとんどのリストは意図通りに呈示されるはずとはいえ、リスト中の内容のための規則は数点違っています。選択した点と相違についての議論は「狙い」と題したリスト項目の項にあります。仕様の提案内容は人間の書き手ないし読み手が直感的に理解するであろう形でリストを呈示するという点において既存のどの実装より良いものであると考えています（ほぼすべての既存の実装で散々な結果に至る完璧に自然な見た目のリストの例はいくらでも与えられるでしょう）。
中黒の文字が変わる、または中黒から数字へ変わるかその逆になると、新しいリストが始まります。これはほぼほぼ書き手の意図に沿うものになると考えています。
順序付きリスト項目を始める数字には.ないし)のいずれかが後に続いて構いません。区切りの様式を変えると新しいリストが始まります。
順序リストが、最初のリストの番号から始まるようになります。
有塀コードブロックに対応しており、抑音符 (```) ないしチルダ (~~~) のいずれかで区切られます。

貢献

CommonMarkを議論するための公開討論の場があります。質問や自由な議論になる可能性の高いものについてはgithubのイシューの代わりにこちらをお使いください。 githubのイシュートラッカーは単純で、明快で、着手できるイシューでのみ使ってください。

執筆者

この仕様はJohn MacFarlene氏によって書かれましたが、それは以下によるものです。

正規表現の置換に基づかない最初のMarkdownの構文解析器 (pandoc) やPEG文法に基づく最初のmarkdownの構文解析器 (peg-markdown、lunamark) を含む、様々な言語でMarkdownの実装を書き保守してきた経験。
BabelMark 2を使い既存のMarkdownの実装間の違いを詳細に調査したこと。
David Greenspan氏、Jeff Atwood氏、Vicent Marti氏、Neil Williams氏、Benjamin Dumke-von der Ehe氏との広範な議論。

最初の告知をして以来、多くの方々が発想を貢献してくださいました。とりわけKārlis Gaņģis氏は強調、強い強調、リンク、画像の規則を練る上でご尽力いただきました。