CommonMark：Markdownの正式な仕様

CommonMarkは、元のMarkdown仕様を取り巻く曖昧さや矛盾を取り除くことを目的とした仕様を備えた、Markdown構文の合理化されたバージョンです。 これは、言語の共通構文を定義する標準化された仕様と、この仕様に対してMarkdown実装を検証するための一連の包括的なテストを提供します。

GitHubは、ユーザーコンテンツのマークアップ言語としてMarkdownを使用します。

「CommonMarkは、インターネット上の多くのWebサイトで使用されるMarkdown構文を、実際の使用法を反映する方法で正式に指定する野心的なプロジェクトです[...]これにより、開発者に提供している間、人々はいつもと同じようにMarkdownを使用し続けることができます。プラットフォーム間で一貫した方法でMarkdownを相互運用および表示するための、包括的な仕様とリファレンス実装。」

—「GitHubフレーバーマークダウンの正式な仕様」、GitHubブログ

2012年、GitHubは独自のMarkdownフレーバー（GitHub Flavoured Markdown（GFM））を作成し、Markdown標準化の欠如に対処し、構文をニーズに合わせて拡張しました。 GFMは、当時の既存のMarkdownパーサーのいくつかの欠点を解決するためにGitHubによって特別に構築されたパーサーであるSundownの上に構築されました。 5年後の2017年に、CommonMarkの解析とレンダリングライブラリを支持するSundownの廃止を発表しました。これは、GitHubFlavouredMarkdownの正式な仕様に記載されています。

MarkdownおよびVisualStudio Codeの「よくある質問」セクションでは、VSCodeのMarkdownが、それ自体がCommonMark仕様に従っているmarkdown-itライブラリを使用してCommonMarkMarkdown仕様を対象としていることが文書化されています。

CommonMarkは、C（cmarkなど）、C＃（CommonMark.NETなど）、JavaScript（markdown-itなど）などのさまざまな言語で使用するために広く採用および実装されています（CommonMark実装のリストを参照）。これは開発者にとって朗報です。そして、著者は、一貫した構文と標準化された仕様でMarkdownを使用できるという新しいフロンティアに徐々に移行しています。

マークダウンパーサーに関する簡単なメモ

マークダウンパーサーは、マークダウンテキストを直接または間接的にHTMLに変換する中心的な役割を果たします。

cmarkやcommonmark.jsのようなパーサーは、Markdownを直接HTMLに変換せず、代わりに抽象構文木（AST）に変換してから、ASTをHTMLとしてレンダリングし、プロセスをよりきめ細かく操作しやすくします。 たとえば、解析（AST）とレンダリング（HTML）の間に、Markdownテキストを拡張できます。

CommonMarkのマークダウン構文のサポート

特定のフレーバーのベースラインとしてすでにCommonMark仕様を実装しているプロジェクトまたはプラットフォームは、多くの場合、CommonMarkMarkdown仕様の厳密なサブセットのスーパーセットです。 そのほとんどの部分で、CommonMarkは、構築されるように構築された仕様を構築することにより、多くのあいまいさを軽減しました。 GFMは代表的な例であり、すべてのCommonMark構文をサポートしますが、使用法に合わせて拡張することもできます。

CommonMarkの構文サポートは、最初は制限される可能性があります。たとえば、このテーブル構文はサポートされていませんが、この会話スレッドのこのコメントが明らかにしているように、これは仕様によるものであることを知っておくことが重要です。サポートされている構文は厳密であり、言語自体のコア構文になります—その作成者であるJohn GruberがMarkdown：Syntaxで指定したものと同じです。

これを書いている時点で、サポートされている構文は次のとおりです。

1. 段落と改行、
2. ヘッダー、
3. 強調と強い強調、
4. 水平方向のルール、
5. リスト、
6. リンク、
7. 画像、
8. ブロッククォート、
9. コード、
10. コードブロック。

例に従うために、commonmark.js dingusエディターを使用して構文を試し、レンダリングされたプレビュー、生成されたHTML、およびASTを取得することをお勧めします。

段落と改行

Markdownでは、段落は少なくとも空白行で区切られたテキストの連続行です。

次のルールは段落を定義します。

1. マークダウン段落は、Paragraph要素<p>としてHTMLでレンダリングされます。
2. 異なる段落は、それらの間に1つ以上の空白行で区切られます。
3. 改行の場合、段落は2つの空白スペース（またはそれに相当するタブ）または円記号（ \ ）で後置する必要があります。

• 段落について学ぶためのインタラクティブなチュートリアル。
• DingusパーマリンクはプレビューとASTで完全な例をチェックしてください。
• 段落の詳細をご覧ください。

見出し

Markdownの見出しは、HTMLの見出し要素の1つを表します。 見出しを定義する方法は2つあります。

1. ATXの見出し。
2. Setextの見出し。

次のルールはATXの見出しを定義します。

1. 見出しレベル1（ h1 ）から見出しレベル6（ h6 ）までがサポートされます。
2. Atxスタイルの見出しには、接頭辞としてハッシュ（ # ）記号が付いています。
3. テキストとハッシュ（ # ）記号を区切るには、少なくとも空白スペースが必要です。
4. ハッシュの数は、見出しの基数に相当します。 1つのハッシュはh1つのハッシュ、 h2つのハッシュ、 h6です。
5. 見出しに任意の数のハッシュ記号を追加することもできますが、これによる影響はありません（つまり、 # Heading 1 # ）

次のルールは、Setextの見出しを定義します。

1. 見出しレベル1（h1）と見出しレベル2（h2）のみがサポートされます。
2. Setextスタイルの定義は、それぞれ等しい（=）記号とダッシュ記号を使用して行われます。
3. Setextでは、少なくとも1つの等しい記号またはダッシュ記号が必要です。

• 見出しについて学ぶためのインタラクティブなチュートリアル。
• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• ATXの見出しの詳細をご覧ください。
• Setextの見出しの詳細をご覧ください。

強調と強い強調

Markdownの強調は、斜体または太字（強く強調）のいずれかになります。

次のルールは強調を定義します。

1. 通常の強調と強い強調は、それぞれ強調<em>要素と強い<strong>要素としてHTMLでレンダリングされます。
2. 単一のアスタリスク（ * ）またはアンダースコア（ _ ）で囲まれたテキストが強調されます。
3. 二重アスタリスクまたはアンダースコアで囲まれたテキストは、非常に強調されます。
4. 境界記号（アスタリスクまたはアンダースコア）は一致する必要があります。
5. 記号と囲まれたテキストの間にスペースがあってはなりません。

• 強調について学ぶためのインタラクティブなチュートリアル。
• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• 強調と強い強調についての詳細をご覧ください。

水平方向のルール

水平方向のルール<hr />は、新しい行に3つ以上のアスタリスク（ * ）、ハイフン（ - ）、またはアンダースコア（ _ ）を使用して作成されます。 記号は任意の数のスペースで区切られるか、まったく区切られません。

• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• テーマ別休憩の詳細をご覧ください。

リスト

Markdownのリストは、箇条書き（順序なし）リストまたは順序付きリストのいずれかです。

次のルールでリストを定義します。

1. 箇条書きリストは、順序付けされていないリスト要素<ul>としてHTMLでレンダリングされます。
2. 順序付きリストは、順序付きリスト要素<ol>としてHTMLでレンダリングされます。
3. 箇条書きリストでは、マーカーとしてアスタリスク、プラス記号、およびハイフンを使用します。
4. 順序付きリストでは、数字の後にピリオドまたは閉じ括弧が続きます。
5. マーカーは一貫している必要があります（リストアイテムの残りの定義には、最初に使用したマーカーのみを使用する必要があります）。

• リストについて学ぶためのインタラクティブなチュートリアル。
• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• リストアイテムの詳細をご覧ください。

リンク

リンクは、インラインおよび参照形式でサポートされています。

次のルールはリンクを定義します。

1. リンクは、HTMLアンカー要素<a>としてレンダリングされます。
2. インライン形式の構文は次のとおりです。 [value](URL "optional-title")括弧の間にスペースはありません。
3. 参照形式の構文は次のとおりです。参照の場合は[value][id] 、ハイパーリンクラベルの場合は[id]: href "optional-title"で、少なくとも1行で区切られます。
4. idは定義識別子であり、文字、数字、スペース、句読点で構成されます。
5. 定義識別子は大文字と小文字を区別しません。
6. URLが小なり記号（<）と大なり記号（>）で囲まれ、文字どおりに表示される自動リンクもサポートされています。

 <!--Markdown--> [Google](https://google.com “Google”) <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> [Google](https://google.com) <!--Rendered HTML--> <a href="https://google.com">Google</a> <!--Markdown--> [Comparing Styling Methods in Next.js](/2020/09/comparing-styling-methods-next-js) <!--Rendered HTML--> <a href="/2020/09/comparing-styling-methods-next-js">Comparing Styling Methods In Next.js</a> <!--Markdown--> [Google][id] <!--At least a line must be in-between--> <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> <https://google.com> <!--Rendered HTML--> <a href="https://google.com">google.com</a> <!--Markdown--> <[email protected]> <!--Rendered HTML--> <a href="mailto:[email protected]">[email protected]</a>

• リンクについて学ぶためのインタラクティブなチュートリアル。
• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• リンクの詳細をご覧ください。

画像

Markdownの画像は、リンクのインライン形式と参照形式に従います。

次のルールで画像を定義します。

1. 画像は、HTML画像要素<img>としてレンダリングされます。
2. インライン形式の構文は次のとおりです![alt text](image-url "optional-title") 。
3. 参照形式の構文は次のとおりです。参照の場合は![alt text][id] 、画像ラベルの場合は[id]: image-url "optional-title" 。 両方とも、少なくとも空白行で区切る必要があります。
4. 画像のタイトルはオプションであり、image-urlは相対的なものにすることができます。

 <!--Markdown--> ![alt text](image-url "optional-title") <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" /> <!--Markdown--> ![alt text][id] <!--At least a line must be in-between--> <!--Markdown--> <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" />

• 画像について学ぶためのインタラクティブなチュートリアル。
• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• 画像の詳細をご覧ください。

ブロッククォート

HTMLブロック引用要素<blockquote>は、新しい行の前に大なり記号（ > ）を付けることで作成できます。

 <!--Markdown--> > This is a blockquote element > You can start every new line > with the greater than symbol. > That gives you greater control > over what will be rendered. <!--Rendered HTML--> <blockquote> <p>This is a blockquote element You can start every new line with the greater than symbol. That gives you greater control over what will be rendered.</p> </blockquote>

ブロッククォートはネストできます：

 <!--Markdown--> > Blockquote with a paragraph >> And another paragraph >>> And another <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <blockquote> <p>And another paragraph</p> <blockquote> <p>And another</p> </blockquote> </blockquote> </blockquote>

また、ヘッダー、コード、リストアイテムなど、他のMarkdown要素を含めることもできます。

 <!--Markdown--> > Blockquote with a paragraph > # Heading 1 > Heading 2 > - > 1. One > 2. Two <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <h1>Heading 1</h1> <h2>Heading 2</h2> <ol> <li>One</li> <li>Two</li> </ol> </blockquote>

• ブロッククォートについて学ぶためのインタラクティブなチュートリアル。
• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• Blockquotesの詳細をご覧ください。

コード

HTMLインラインコード要素<code>もサポートされています。 1つを作成するには、テキストをバックティック（ `）で区切るか、囲んでいるテキストに文字通りのバックティックが必要な場合はダブルバックティックを使用します。

 <!--Markdown--> `inline code snippet` <!--Rendered HTML--> <code>inline code snippet</code> <!--Markdown--> `<button type='button'>Click Me</button>` <!--Rendered HTML--> <code><button type='button'>Click Me</button></code> <!--Markdown--> `` There's an inline back-tick (`). `` <!--Rendered HTML--> <code>There's an inline back-tick (`).</code>

• コードについて学ぶためのインタラクティブなチュートリアル。
• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• コードスパンの詳細をご覧ください。

コードブロック

HTMLのフォーマット済みテキスト要素<pre>もサポートされています。 これは、少なくとも3つと同じ数のバウンディングバックティック（ ` ）、またはチルダ（ ~ ）—通常はコードフェンスと呼ばれる、または少なくとも4つのスペースのインデントを開始する改行を使用して実行できます。

 <!--Markdown--> ``` const dedupe = (array) => [...new Set(array)]; ``` <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre> <!--Markdown--> const dedupe = (array) => [...new Set(array)]; <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>

• コードについて学ぶためのインタラクティブなチュートリアル。
• プレビューとASTで完全な例をチェックするためのDinguspermalink。
• フェンスで囲まれたコードブロックとインデントされたコードブロックの詳細をご覧ください。

インラインHTMLの使用

インラインHTMLに関するJohnGrubersの元の仕様書によると、Markdownの構文でカバーされていないマークアップは、HTML自体を使用するだけです。唯一の制限は、ブロックレベルのHTML要素です（例： <div> 、 <table> 、 <pre> ） <pre> 、 <p>など—空白行で周囲のコンテンツと区切る必要があり、ブロックの開始タグと終了タグをタブやスペースでインデントしないでください。

ただし、おそらくCommonMark自体の背後にいる人、またはその周辺の人でない限り、現在CommonMarkでサポートされていない多数の構文を処理するためにすでに拡張されているフレーバーを使用してMarkdownを作成する可能性があります。

今後

CommonMarkは、2019年4月6日に最終更新された仕様で常に進行中の作業です。Markdownツールのプールには、CommonMarkをサポートする人気のあるアプリケーションが多数あります。 CommonMarkの標準化への取り組みを認識した上で、Markdownの単純さでは、舞台裏で多くの作業が行われていること、GitHub FlavouredMarkdownの正式な仕様がCommonMarkの取り組みにとって良いことであると結論付けるだけで十分だと思います。仕様に基づいています。

CommonMarkの標準化の取り組みに向けた動きは、サポートされている構文を拡張するためのフレーバーの作成を妨げるものではありません。CommonMarkは、解決する必要のある問題でリリース1.0に向けて準備を進めているため、継続的な取り組みについていくつかの興味深いリソースがあります。熟読。

資力

• ジョン・グルーバーによるマークダウンの紹介
• CommonMark公式ウェブサイト
• GitHubフレーバーマークダウン仕様
• cmark公式リポジトリ
• GitHubのcmarkのフォーク
• ウィキペディアの値下げ
• マークダウンガイド