GitHub Flavored Markdown vs CommonMark：変換ではどちらを選ぶべきか
出力先に合わない Markdown 方言を選ぶと、変換自体は技術的に成功するのに、結果は静かにレンダリングを誤ります。表はただのテキストに、取り消し線はチルダが丸見えに、チェックボックスのリストは箱を失います。修正にコストはかかりませんが、それは変換する前に選んだ場合だけです。
このガイドでは、CommonMark が実際に何を規定しているのか、GitHub Flavored Markdown がその上に何を追加しているのか、どのプラットフォームがどのフレーバーを話すのか、そして Word の下書きと最終的な公開先の間にコンバーターが挟まるとき、この選択が実際にどう影響するのかを説明します。
CommonMark：Markdown のコアを定める一つの仕様
古典的な Markdown は Perl スクリプトに散文の説明が付いたもので、2010年代には数十の実装が基本的なケースで意見が分かれていました。インデントされた段落の後にリストは続くのか、改行をまたぐ強調は何とみなすのか、数字にドットが続く場合はいつリストになるのか。同じファイルがほぼどこでも違う見た目でレンダリングされていました。
CommonMark は正式な仕様でこれに答えました。Markdown のコア構文に対する曖昧さのない文法、それぞれ正解が一つに定まった数百のテスト例、照合に使えるリファレンス実装です。pandoc の作者でもある John MacFarlane も執筆者の一人で、この仕様はすぐに定着しました。
今日、CommonMark はほぼすべてがその上に構築される基盤レイヤーです。表や取り消し線を意図的に含んでいません。定義しているのは、それらの機能が乗る土台だけであり、だからこそ拡張という第二のレイヤーが必要とされたのです。
GFM がその上に追加したもの
2017年に公開仕様として策定された GitHub Flavored Markdown は、CommonMark の厳密な上位集合です。追加されたのは五つ。パイプで書く表、二重チルダの取り消し線、チェックボックス付きのタスクリスト項目、裸の URL の自動リンク、そして特定の生 HTML タグの実行を防ぐフィルターです。
どの追加も、開発者がすでに書いていたものを狙ったものです。パイプの表は依存関係マトリクスやテストマトリクスをカバーし、タスクリストは README をチェックリストに変え、自動リンクは URL をいちいち山括弧で囲む手間を省きます。HTML フィルターはセキュリティ対策で、誰でも編集できるサイトで埋め込み HTML を危険にするタグを取り除きます。
GitHub は cmark-gfm を通じて Markdown をレンダリングしています。これは CommonMark のリファレンス実装のフォークに、これらの拡張を組み込んだものです。GitLab と Gitea も同じ全体構成に従っているため、GFM は主要なコードフォージ間で一貫して動作し、サイトごとに挙動が変わることはありません。
それぞれのフレーバーの本拠地
GFM の本拠地は言うまでもなく GitHub、そしてデフォルトで GFM を採用する静的サイトツールです。Hugo は最初から GFM 用に設定されたエンジンでレンダリングし、MkDocs は表を標準で有効にします。Obsidian はパイプの表、取り消し線、タスクリストという三つの代表的な構文をすべて受け入れ、その上に独自の方言機能を追加しています。
厳密な CommonMark パーサーは、小さく予測可能なコアをあえて好むライブラリやブログエンジンに存在します。pandoc 自身のデフォルトの Markdown は第三のフレーバーで、グリッド表や引用構文など、GitHub がレンダリングしない拡張を含む大きな上位集合です。
だからといって、どちらのフレーバーが優れているという話にはなりません。問うべきは抽象的にどちらの方言が勝つかではなく、出力先が実際にどの方言をレンダリングするのか、そしてこれから作るファイルがその境界内に収まっているかどうかです。
コンバーターがこの違いを気にする理由
コンバーターは構文を翻訳するだけでなく、出力する方言を選んでいます。選択が最も目に見えるのは表です。出力先が GitHub で、出力方言がパイプの表をサポートしていれば、単純な表は表のまま届きます。サポートしていなければ、同じ表は出力先が無視する構文にフォールバックし、読者には縦棒の入ったプレーンテキストの行が見えることになります。
取り消し線やタスクリストのチェックボックスも同じように、ただ目立たない形で失敗します。テキストにチルダが残り、チェックボックスの括弧がそのままレンダリングされます。文書が実際に壊れているわけではなく、読者のレンダラーが知らない言語を話しているだけです。
これは、ソース形式が思っているほど重要ではない理由でもあります。pandoc は docx であれ CSV であれ、入力を抽象ドキュメントモデルに解析し、方言の決定は出力を書き出すときに行われます。reader は一つ、writer は多数。そしてあなたが制御できるのは writer のほうです。
出力先で選ぶ
コードフォージや保管庫（vault）に置くものには GFM を選びましょう。GitHub のプルリクエスト、GitLab の wiki、Obsidian のノート、Hugo のサイトはいずれもその構文をレンダリングします。厳密な CommonMark をうたうブログエンジンやライブラリには、プレーンな CommonMark を選び、表には HTML や拡張によるフォールバックが必要になると想定してください。
出力先がわからない場合、GFM がより安全なデフォルトです。目に見える四つの追加機能は Markdown の世界で最も広くサポートされている拡張であり、その一つを省略しているプラットフォームでも、生の構文を見せるのではなく、たいていは自然に機能を落とす形で済みます。
避ける価値のある唯一の間違いは、上位集合なら常に安全だと思い込むことです。pandoc Markdown のグリッド表や引用構文で書かれたファイルは pandoc では問題なく見えても、GitHub では壊れます。出力先が解析できないリッチな方言を出力するより、出力先の方言を出力するほうが常に勝ります。
変換で GFM スイッチが変えるもの
このサイトのコンバーターは、この選択を一つのスイッチとして提供しています。GFM を有効にすると、Markdown 出力はパイプの表を使い、取り消し線とタスクリストの構文をそのまま保ち、生の HTML 画像タグやリンクに付く幅属性のような、GitHub がレンダリングしない構文を避けます。
有効にしない場合、出力は pandoc 独自の Markdown フレーバーに従います。完全に有効で読みやすいままですが、複雑な表は GitHub が無視する方言で出力されることがあり、CommonMark のコアを超える機能は、向こう側でおなじみの GFM の形になる保証はありません。
このスイッチには、知っておく価値のある静かな相互作用がもう一つあります。CSV や TSV の入力では結果が表のドキュメントになりますが、GFM モードこそが、その表を GitHub が無視する亜種ではなく、実際にレンダリングするパイプ構文のまま保つ役割を果たします。
改行というエッジケース
改行は、ほかのどんな選択をしても残る違いです。CommonMark では、段落内の単一の改行はソフトブレークで、スペースとしてレンダリングされます。ハードブレークにするには行末にスペースを二つ入れるか、バックスラッシュが必要です。GFM もファイルについてはこのルールを守ります。
現実はもっと複雑です。GitHub のコメントや issue の本文は単一の改行を目に見える改行として扱い、Obsidian も設定で厳密な改行を有効にしない限り、デフォルトで同じ動作をします。そのため、文の途中で折り返した段落は、GitHub では一つの見え方になり、隣の README では別の見え方になります。
実践ルールはこうです。出力が CommonMark や GFM のときは段落を一つの長い行として書き、改行がそのまま改行になるとプラットフォームが明示している場所でのみそれに頼ること。方言選択に関するほかのことはすべて後から直せますが、改行だけは見えているのに隠れている問題です。