ブログに戻る
Reference 2026-04-26

Markdownフレーバー比較: CommonMark, GFM, MDX

ドキュメント、ブログ、CMSに適したMarkdownフレーバーを選択。

Markdownは一つの言語ではなく、たまたま同じ姓を共有する方言の一族です。John Gruberの2004年のオリジナルはPerlスクリプトと非公式な説明であり、核心的な問いを未解決のまま残しました。強調マーカーはどうネストするのか? どれだけのインデントがリスト項目を継続するのか? ネストしたブロックの前に空行は必要か? すべての実装が異なる答えを出し、だからこそ同じ文書が3つのプラットフォームで3通りにレンダリングされ得るのです。主要なフレーバーを、そして自分のツールチェーンが実際にどれを話しているのかを理解すれば、フォーマットの驚きというバグの一群がまるごと消えます。

CommonMark: 形式的なベースライン

CommonMark(2014年、Pandocで有名なJohn MacFarlane主導)は、非公式な説明を600以上の適合性例と2つのリファレンス実装(C言語のcmark、commonmark.js)を備えた厳密な仕様に変えました。パーサーごとに異なっていた曖昧さを正確に固定します。

  • 正確な強調ルール: デリミタが強調を開くか閉じるかは左右フランキングデリミタランで決まります。単語内部のアスタリスクのペアはイタリックになるのに、空白に囲まれたアスタリスクがそのまま残る理由です
  • リストの継続: コンテンツが項目のコンテンツ列までインデントされていればその項目に属する。魔法の4スペースではない
  • それぞれ固有の開始・終了条件を持つ7種類のHTMLブロック
  • 優先順位: リンク構文は強調に勝ち、コードスパンはあらゆるインラインに勝つ

コンテンツが多くのツールで同一にレンダリングされる必要があるなら、CommonMarkに合わせて書き、それが定義しないものを避けましょう。

レベル1見出し


===========
__太字__ と _イタリック_ と コード

[リンク](https://example.com)
1. 順序付き項目


   コンテンツ列までインデントした継続段落

GFM: CommonMarkに開発者の必需品を加えたもの

GitHub Flavored Markdownは形式的には厳密なスーパーセットです。GitHubはこれを、CommonMarkにちょうど5つの拡張(テーブル、タスクリスト項目、取り消し線、オートリンク、危険な生HTMLタグを除去するtagfilter)を加えた仕様として公開しています。脚注、絵文字ショートコード、メンションはGFM仕様ではなく、その上に載ったGitHubプラットフォーム機能です。別の「GFM互換」レンダラーが脚注を拒否するとき、この違いが効いてきます。

|カラム|型  |


|------|----|


|id    |int |
* [x] リリース済み


* [ ] 保留中
~~非推奨~~ と https://autolinked.example.com

微妙な相違点を一つ: .md ファイルではGitHubは仕様どおり単一改行をソフトブレークとして扱いますが、イシューとコメントでは単一改行がハードラインブレークになります。2つのコンテキスト間でテキストをコピーするとレンダリングが変わります。

MDX: コンパイルされるMarkdown

MDXはマークアップ方言というよりコンパイルターゲットです。各ファイルがESモジュールになります。コンポーネントをインポートし、値をエクスポートし、JSXを埋め込み、式をインラインで評価できます。

import { Chart } from '../components/Chart';


export const data = [4, 8, 15, 16];
合計は {data.reduce((a, b) => a + b, 0)} です。
<Chart values={data} />

この力には実際のコストが伴います。生HTMLはもう素通りしません。山括弧のコンテンツはJSXとして解析されるため、class は className にしなければならず、<br> のような閉じられていないタグは構文エラーになり、はぐれた { 一つが式を開始します。1つの文書のビルドエラーがサイト全体のビルドを壊し得て、非開発者の貢献者はMarkdownを魅力的にしていた「ただのテキスト」という保証を失います。文書が本当にライブコンポーネントを必要とするとき(インタラクティブなドキュメント、デザインシステム)はMDXを、全員が書きレビューする必要があるときはGFMを選びましょう。

より広い一族

  • Pandoc Markdown — 学術界の強者: 引用、数式、定義リスト、属性ブロック、LaTeX・DOCXなどへの変換。
  • Djot — Markdownのパースの疣を取り除いたMacFarlaneのポストCommonMark実験(怠惰な継続なし、インデントの曖昧さなし)。注目に値するがまだ主流ではない。
  • markdown-it, remark, goldmark, comrak — パーサー層。remarkは文書をプラグインパイプライン付きのASTとして公開し(MDXと大半のReactドキュメントフレームワークの基盤)、goldmarkはHugoを動かし、comrakはRustのGFM実装です。

セキュリティノート

Markdownの生HTML素通しは、ユーザー投稿のMarkdownがデフォルトでXSSベクトルであることを意味します。信頼できない入力のレンダリングパイプラインには、レンダリング後のサニタイズが必要です。HTML出力にrehype-sanitizeかDOMPurifyを。Markdownソースへの正規表現フィルタリングは確実にバイパス可能です。

選択

  • README、Wiki、チームドキュメント: GFM
  • インタラクティブなドキュメントサイト: MDX (Docusaurus、Astro、Next.js)
  • レンダラー間の最大の移植性: 厳格なCommonMark
  • 学術・印刷向けの執筆: Pandoc

フロントマターと数式

あまりに一般的でコアMarkdownのように感じられるのに、どの仕様にも属さない拡張が2つあります。YAMLフロントマター — ファイル先頭の --- フェンスの間のメタデータ — はJekyllが広めた静的サイトの慣習です。プラグインが取り除かない限り、CommonMarkパーサーはこれをテーマ区切りとそれに続くテキストとして扱います。数式も同様です。$x^2$ スパンと $$...$$ ブロックはremark-math、markdown-it-texmath、あるいはプラットフォーム側のKaTeX/MathJaxレンダリングで処理され、空白とエスケープをめぐるデリミタ規則がそれぞれ微妙に異なります。どちらの機能もプラグインのないレンダラーでは静かに目に見えるゴミへと劣化するため、パイプラインがどの拡張を有効にしているかを文書化しましょう。リポジトリREADMEの一行が「なぜメタデータがそのまま表示されるのか」というバグ報告の大半を防ぎます。

sdk.is/markdown-editor のMarkdownエディタで、書きながら文書のレンダリングをプレビューしましょう。