Markdown の方言：CommonMark と GFM、その他の拡張

「Markdown」と一口に言っても、仕様は複数あります。本記事では主要な方言（フレーバー）と、書く時に注意すべき差分を整理します。

なぜ方言が生まれたか

オリジナルの Markdown（John Gruber, 2004）は仕様が緩く、実装ごとに挙動がばらついた：

• 表の書き方が定義されていない
• 入れ子のリストの解釈がバラバラ
• 改行（<br>）の扱いが実装依存

これを統一するために CommonMark が、機能を拡張するために GFM などが生まれました。

CommonMark：標準仕様

CommonMark は厳密な仕様。多くの Markdown ツールが準拠：

• 入れ子のリスト、引用、コードブロックの挙動を明確化
• 「テーブル」「タスクリスト」「打ち消し線」は含まれない（拡張）
• pandoc、commonmark.js、cmark などが実装

CommonMark のみでは「最近の Markdown らしさ」が出ない。

GitHub Flavored Markdown (GFM)

GitHub で使われる方言。CommonMark の上位互換 + 独自拡張：

拡張要素

| 列 1 | 列 2 |
| ---- | ---- |
| a    | b    |

- [x] 完了したタスク
- [ ] 未完了

~~打ち消し線~~

https://example.com（自動リンク）

主な独自仕様

• 表（テーブル）：パイプとハイフン
• タスクリスト：[ ] [x]
• 打ち消し線：~~text~~
• 自動リンク：http://... を自動でリンク化
• 絵文字ショートコード：:smile: → 😄

GitHub、GitLab、Bitbucket、ほとんどのドキュメントサービスは GFM 互換。

MDX

JSX をマークダウン内に書ける拡張。React コンポーネントを直接埋められる：

import Chart from './Chart';

# データ可視化

<Chart data={[1, 2, 3]} />

• Docusaurus、Next.js、Astro などで使用
• 「動的な要素を含むドキュメント」に向く

mdsvex（Svelte 版 MDX）

Svelte コンポーネントを Markdown に埋め込める：

<script>
  import Counter from './Counter.svelte';
</script>

# 見出し

<Counter />

SvelteKit のドキュメントサイトでよく使われる。

Pandoc Markdown

Pandoc の独自フレーバー：

• 数式（LaTeX）
• 引用文献の脚注
• 表の captions
• 定義リスト
• フッターやヘッダーのカスタマイズ

学術文書・書籍向けに強力。GFM の上位互換ではない（独立した仕様）。

Obsidian / Bear Markdown

ノートアプリの独自拡張：

• Wiki リンク：[[ノート名]]
• タグ：#tag
• ハイライト：==重要==
• 画像埋め込み：![[image.png]]

これらは GFM や CommonMark には含まれない。

ZennとQiitaの拡張

日本のエンジニア向けプラットフォームの拡張：

:::message
情報メッセージ
:::

:::message alert
警告メッセージ
:::

• 「メッセージボックス」
• 「キャプション付きコードブロック」
• 「外部リンクのカード化」（URL のみの行）

GFM 互換ではあるが、独自構文を含む。

よくある互換性の罠

改行

CommonMark は「行末の半角スペース 2 つ」で改行：

こんにちは ← スペース2つ
世界

GFM は「単純な改行」を <br> に変換するモードがある（GitHub 上の Issue / PR）。READMEなど通常文書ではされない。

リストとパラグラフの間

- リスト 1

これはパラグラフ

CommonMark：パラグラフはリストの外。 一部のツール：リストアイテムの続きとして扱う場合がある。

番号付きリストの開始番号

3. 三番目から始まるリスト
4. 続き

CommonMark：3 から始まる。 古い実装：1 にリセットされる。

コードブロック内の HTML エンティティ

```

<div>
```

ほとんどのフレーバーで <div> がそのまま表示される（HTML として解釈されない）。だが古い実装では混乱することも。

表の制約

GFM の表には制約があります：

• 列内で改行できない：<br> を使うか避ける
• 複数行のセルが書けない：見た目だけ複数行は不可
• 整形が崩れやすい：列幅が違うと読みづらい

複雑な表が必要なら HTML を直接書く：

<table>
	<tr>
		<td>複数行<br />セル</td>
	</tr>
</table>

数式

CommonMark は数式をサポートしない。拡張：

• GFM: KaTeX をサポート（GitHub の README で $ ... $ $$ ... $$）
• Pandoc: LaTeX 数式
• MDX: KaTeX や MathJax のコンポーネント

インライン数式：$E = mc^2$

ブロック数式：

$$
int_a^b f(x) dx
$$

内部リンク（アンカー）

見出しに自動でアンカーが生成される：

## 私のセクション

[セクションへ](#私のセクション)

スラグ生成ルールはツールによって違う：

• GFM：小文字化、空白をハイフンに、特殊記号を削除
• 一部の実装：日本語をローマ字化したり、削除したり

「相互リンクが切れる」のはたいていこれが原因。

エスケープ

* や _ などをそのまま表示するにはバックスラッシュ：

*強調しない*

GFM は ~ < > などの追加文字も対応。

まとめ

• CommonMark が標準、GFM が事実上のデファクト
• ツール独自の拡張（MDX、Obsidian、Zenn など）は移植しづらい
• 表・数式・改行は方言差が出やすい
• 移植性を重視するなら GFM の範囲で書く

Markdown の表示確認やフォーマット確認には、本サイトの Markdown プレビューが使えます。