TL;DR — GFM テーブル早見表
GFM テーブルは GitHub Flavored Markdown 仕様で定義されたパイプ区切りの表で、素の CommonMark には含まれない拡張機能です。
- 表は「ヘッダー行 / 区切り行（
---、3 つ並べるのが慣習）/ データ行」をパイプ|で区切るだけ。表の前後には空行が必要。 - 配置は区切り行のコロンで指定:
:---左寄せ /:---:中央 /---:右寄せ。 - セル内のパイプはバックスラッシュで
\|、効かない環境では HTML エンティティ|をフォールバックに。 - セル内改行は
<br>を直接書く。GitHub / GitLab では動くが、Obsidian / Notion ほかは編集モードや取り込み経路で結果が変わる。 - セル結合・複数段落・コードブロックなどブロック要素は GFM テーブルでは不可。必要なら HTML の
<table>に切り替える。 - 手書きが面倒なら CSV to Markdown に CSV を貼るだけで GFM 互換のテーブルが出力されます。
この記事は、すでに Markdown の表をある程度書ける人が記法をすばやく確認するための早見表です。表をゼロから順を追って学びたい場合は Markdown 表の書き方: 配置・エスケープ・コピペできる例 を先に読んでください。
GFM テーブルでできること・できないこと
| できること | できないこと |
|---|---|
| ヘッダー + データ行の表 | ヘッダーなしの表（ヘッダー行は必須） |
| 列ごとの左寄せ・中央・右寄せ | 列幅の数値指定 |
| セル内のインライン書式（コード・リンク・画像・強調・取り消し線） | セル内のコードブロック・リスト・複数段落（ブロック要素） |
<br> による見かけの改行（環境依存） | セルの行結合・列結合（rowspan / colspan） |
| パイプや特殊文字のエスケープ | 表内の見出し（#）や引用（>）ブロック |
ブロック要素やセル結合が必要なときは Markdown ではなく HTML の <table> を直接書きます（後述の「Markdown 表で無理なこと」を参照）。
基本構造 — 最小ペアで確認
GFM テーブルはヘッダー行・区切り行・データ行の 3 パーツです。区切り行のハイフンは各列 3 つが慣習（GFM 仕様に最低本数の規定はありません）、行頭行末のパイプは省略可です。
記法:
| 名前 | 権限 |
| --- | --- |
| 田中 | admin |
| 鈴木 | viewer |
結果:
| 名前 | 権限 |
|---|---|
| 田中 | admin |
| 鈴木 | viewer |
最小の表（ヘッダー 1 行 + データ 1 行）はこうなります。
| key | value |
| --- | --- |
| name | FormatArc |
アラインメント記法早見表
区切り行のコロンの位置で列の配置を指定します。
| 記法 | 配置 |
|---|---|
:--- | 左寄せ（コロンなしと同じ） |
:---: | 中央揃え |
---: | 右寄せ |
記法:
| 商品 | 数量 | 単価 |
| :--- | :---: | ---: |
| りんご | 3 | 120 |
| みかん | 10 | 80 |
結果:
| 商品 | 数量 | 単価 |
|---|---|---|
| りんご | 3 | 120 |
| みかん | 10 | 80 |
数値列を右寄せにすると桁が揃って読みやすくなります。
セル内で使える書式
セル内ではインライン要素が使えます。コードブロックやリスト、複数段落は使えません。
| 入れたいもの | 記法（セル内に書く） | 結果 |
|---|---|---|
| インラインコード | `npm run build` | npm run build |
| リンク | [FormatArc](https://formatarc.com/) | FormatArc |
| 画像 |  | （画像が表示される） |
| 強調 | *斜体* / **太字** | 斜体 / 太字 |
| 取り消し線 | ~~削除~~ | |
| 改行 | 1 行目<br>2 行目 | 1 行目 2 行目 |
画像はセルに入れられますが、表が縦に伸びて読みにくくなりがちなのでサイズの小さいアイコン程度に留めるのが現実的です。
空セル・ブランクセルの書き方
セルを空にするのは問題ありません。パイプの間に何も書かなければ、そのセルは空白で表示されます。
記法:
| 名前 | 権限 | メモ |
| --- | --- | --- |
| 田中 | admin | |
| 鈴木 | | viewer |
結果:
| 名前 | 権限 | メモ |
|---|---|---|
| 田中 | admin | |
| 鈴木 | viewer |
つまずきやすいのは次の 2 点です。
- 列数は揃えたままにする。空セルは
| |（パイプ 2 本の間が空）であって、パイプを省くことではありません。パイプを 1 本減らすと列が 1 つ足りなくなり、表が崩れます。 - 行の先頭セルが空で、かつ行頭のパイプも省略すると、レンダラーによっては行の最初の列が失われることがあります。行頭の
|を残す（| | 値 |）か、フォールバックとして先頭セルに空リンク[]()を置くと、欠落扱いを防げます。
空セルはセル結合ではありません。GFM には rowspan / colspan が無いため、空白のセルはあくまで空白で、上や横のセルと視覚的に結合することはありません。結合が必要なら HTML の <table> に切り替えます（後述）。
パイプ・特殊文字のエスケープ早見表
セルに | をそのまま書くと列区切りと誤認されてテーブルが崩れます。安全な書き方は 2 つあります。
| 方式 | 記法 | 対応 |
|---|---|---|
| バックスラッシュエスケープ | cmd1 | cmd2 | GitHub / GitLab / Notion / Obsidian / Zenn / Qiita など主要な GFM レンダラーで動作（GitHub 公式が明示） |
| HTML 数値文字参照 | cmd1 | cmd2 | レンダラーが | を正しく扱えない場合のフォールバック。エディタ間でコピペしても壊れにくい |
記法:
| コマンド | 意味 |
| --- | --- |
| cmd1 \| cmd2 | バックスラッシュでエスケープ |
| cmd1 | cmd2 | HTML エンティティで記述 |
結果:
| コマンド | 意味 |
|---|---|
| cmd1 | cmd2 | バックスラッシュでエスケープ |
| cmd1 | cmd2 | HTML エンティティで記述 |
そのほか、バックスラッシュ自体を表示したいときは \\、改行しない空白を入れたいときは を使います。CSV や HTML から表を作る場合、パイプのエスケープは CSV to Markdown や HTML to Markdown が自動でやってくれるので手で気にする必要はありません。
セル内改行とプラットフォーム別の可否
Markdown テーブルの仕様上、セル内で生の改行は書けません。見かけ上の改行を入れたいときは HTML タグ <br> を直接書きます。ただし環境差があります。
| プラットフォーム | セル内 <br> の改行 | 補足 |
|---|---|---|
| GitHub | 動く | 公式ドキュメントに記載あり |
| GitLab | 動く | 公式ドキュメントでセル内改行用途として明記 |
| Obsidian | だいたい動く | 編集モード（ライブプレビュー / リーディングビュー）で見え方が変わることがある |
| Notion | 取り込み経路依存 | Markdown インポート時に拡張記法が崩れることがあり、<br> も期待どおりにならない場合がある |
| Zenn / Qiita | 動く環境が多い | プラットフォームのレンダラー仕様に従う |
確実に改行したい列が多い表は、そもそも GFM テーブルに無理に押し込まず HTML の <table> を使うか、列を分けるのが安全です。
テーブルが壊れる原因とチェックリスト
表示が崩れたときは、上から順に確認してください。
- 表の前後に空行があるか — 直前の行と詰まっているとパーサーが表として認識しないことがある（GitHub では特に効きやすい）
- ヘッダー行があるか — GFM ではヘッダー行は必須。ヘッダー不要でも空のヘッダー行と区切り行を書く
- ヘッダー行と区切り行の列数が一致しているか — ここが不一致だとテーブルとして一切認識されない。ハイフンの本数自体は原因にならない（
--でも描画される。各列 3 つは可読性の慣習） - ヘッダーと区切り行とデータ行の列数（パイプの数）が揃っているか — データ行が短いと空セルで補完、長いとはみ出した分が切り捨てられる
- セル内に未エスケープのパイプ
|がないか — ある場合は\|か|に直す - 行頭に余計なインデント（半角 4 つ以上）が無いか — コードブロックと誤認されることがある
- セル内にコードブロックやリストなどブロック要素を入れていないか — GFM テーブルでは使えない
CSV / HTML / JSON からテーブルを自動生成する
5 行程度なら手書きで十分ですが、20 行を超える表や列数の多い表は手作業だとパイプの整列やエスケープでミスが出ます。元データの形式に応じて FormatArc のツールを使うと一発で GFM 互換のテーブルになります。
- CSV / スプレッドシート / Excel のデータから: CSV to Markdown に貼り付けて実行。手順の詳細は CSV を Markdown テーブルに変換する方法、README に載せる場合は GitHub README に表を入れる方法 を参照。
- 既存の HTML（Web ページの表、Notion エクスポート、CMS のダンプ）から: HTML to Markdown に HTML を貼ると
<table>がパイプテーブルに変換されます。詳細は HTML を Markdown に変換する方法。 - JSON（API レスポンスやログ）から: 一度 CSV を経由するのが確実です。配列の各オブジェクトのキーを列名、値を各行のセルにした CSV を作り、CSV to Markdown に渡します。手順は GitHub README に表を入れる方法 の「JSON データからテーブルを作る」を参照。
- 作った Markdown テーブルを Markdown 非対応の CMS や HTML メールに貼りたい場合は Markdown to HTML で HTML に変換できます。手順は Markdown を HTML に変換する方法。
処理はすべてブラウザ内で完結するので、社内データや顧客リストを貼っても外部サーバーには送信されません。登録もアップロードも不要です。
作った表を LLM のプロンプトに渡す場合、Markdown テーブルは同じ内容の HTML よりトークン消費が大幅に少なく、抽出精度も高くなります。実測したトークン数と精度の比較は LLM に渡すなら Markdown か HTML か を参照してください。
Markdown 表で無理なこと — HTML に切り替える目安
次のような表は GFM テーブルでは表現できません。Markdown の中に HTML の <table> を直接書く方法に切り替えます。
- セルの行結合・列結合（
rowspan/colspan）が必要 - セル内に箇条書きや複数段落、コードブロックを入れたい
- 列幅をピクセルや割合で固定したい
- 表内に見出しや別の表をネストしたい
ただし GitHub などはセキュリティ上の理由でテーブル内の HTML を制限していて、<br> は通っても <span style="..."> のようなインラインスタイルは無視されます。色やフォントサイズの変更はできないと考えてください。
なぜ GFM はセル結合 (rowspan / colspan) に対応していないか
GFM 仕様の Tables (extension)別タブで開きます はパイプ区切りの「1 行 = 1 row」を ABNF レベルで要求していて、構造的にセル結合の余地がありません。視認性とパース実装の単純さを優先した結果で、CommonMark に table 拡張を採用する議論でも同じ設計が引き継がれました。結合が必要な表は GFM の射程外と割り切り、HTML の <table> に切り替えるのが現実解です。
HTML <table> で結合する最小コード例
Markdown ファイルの中にそのまま HTML を書くと、GitHub などの GFM レンダラーはそれを HTML として描画します。
列方向の結合 (colspan):
<table>
<tr><td colspan="2">期間 (2026)</td></tr>
<tr><td>4 月</td><td>9 月</td></tr>
</table>
行方向の結合 (rowspan):
<table>
<tr><td rowspan="2">案件 A</td><td>キックオフ</td></tr>
<tr><td>納品</td></tr>
</table>
GitHub が通す HTML 属性・弾く HTML 属性
GitHub は表内の HTML をセキュリティ目的で sanitize していて、構造系の属性は通りますがスタイル系は無視されます。よく使う属性の可否は次のとおりです。
| 属性 | GitHub で有効か | 補足 |
|---|---|---|
colspan / rowspan | 有効 | 結合用途で安全に使えます |
align (td/th) | 有効 | 列単位の配置を上書きできます |
width / height (td) | 一部 | px 値は通ることが多い。% 指定は弾かれる場合あり |
class | 無視 | GitHub のスタイルは自前 CSS で固定 |
style (インラインスタイル) | 無視 | 文字色・背景色・フォントサイズなどは反映されません |
id | 一部 | アンカー生成には使えません |
<script> / on* ハンドラー | 削除 | XSS 防止のため除去されます |
色やフォントサイズで強調したい場合は、表の外に図やバッジを置く、Markdown の **強調** で代用する、画像化してテーブルに貼る、のいずれかになります。
「GFM 以外なら結合できる」拡張記法 (GitHub では使えない)
GitHub ではどれも動きませんが、ローカルの Markdown プレビューや別プラットフォーム向けに書く場合は次のような拡張記法があります。
- VS Code 拡張 Markdown Preview Enhanced別タブで開きます —
>でセルを上に結合、^で左に結合 - Python-Markdown 拡張 mdx_tableau別タブで開きます — colspan / rowspan を Markdown 構文で書ける
- Pandoc grid table / multiline table別タブで開きます —
+---+---+形式で結合を表現可能
GitHub README や Issue 本文で確実に結合させたいなら、これらの拡張記法に頼らず HTML <table> を直接書くのが結局いちばん安全です。
CommonMark とテーブルの関係
素の CommonMark別タブで開きます にはテーブル構文の定義がありません。パイプ区切りのテーブルは GitHub Flavored Markdown 仕様の Tables (extension) セクション別タブで開きます で定義された GFM の拡張機能です。CommonMark のみを厳密に実装し拡張を取り込まないレンダラーでは、| col | がそのまま文字列として表示され、テーブルにはなりません。お使いのツールが「GFM 互換」かどうかは、まず簡単な表を 1 つ書いてみて確認するのが早いです。
よくある質問
最小の Markdown 表はどう書きますか？
ヘッダー行 1 行、区切り行 1 行、データ行 1 行の合計 3 行が最小です。| key | value | の下に | --- | --- |、その下に | name | FormatArc | のように書きます。区切り行のハイフンは各列 3 つ並べるのが慣習ですが、GFM 仕様上は 1 つでも有効です。
セルを空にするにはどう書きますか？
パイプ 2 本の間に何も書かなければ空セルになります（| 値 | |）。列数はヘッダーと揃える必要があるため、空セルは | | であってパイプの省略ではありません。空セルが行の先頭にくる場合は行頭のパイプを残してください（| | 値 |）。行頭パイプと先頭セルの両方が無いと、行の最初の列を落とすレンダラーがあります。空セルはセル結合ではなく、GFM に rowspan / colspan はありません。
\| と | はどちらを使えばいいですか？
まずはバックスラッシュエスケープ \| を使ってください。GitHub の公式ドキュメントでも明示されており、主要な GFM レンダラーで動きます。レンダラーが \| を正しく扱えなかったり、エディタ間でコピペすると壊れる場合のフォールバックとして | を使います。
セル内で文字色やフォントサイズを変えられますか？
GFM テーブルだけでは変えられません。GitHub などはテーブル内の <span style="..."> のようなインラインスタイルを無視するため、色やサイズの変更は反映されません。装飾が必須なら表ごと外側に出して HTML を使うか、別の見せ方を検討してください。
列幅の目安はありますか？
Markdown には列幅を指定する記法がなく、レンダリング時に内容に応じて自動調整されます。実務上は、README やドキュメントを PC とモバイルの両方で読む想定なら列数を 5〜6 列以内に抑えるのが目安です。それを超えると GitHub 上で水平スクロールが発生し読みにくくなります。
セルの結合（rowspan / colspan）はできますか？
GFM テーブルではできません。セル結合が必要な表は Markdown の中に HTML の <table> を直接書きます。ただし GitHub などは一部の HTML 属性を制限するため、複雑なレイアウトは事前に表示を確認してください。
表が表示されず | col | のまま出ます。なぜですか？
主な原因は、表の前後に空行がない、ヘッダー行がない、ヘッダー行と区切り行の列数が揃っていない、レンダラーが GFM テーブル拡張に対応していない（純 CommonMark 実装）のいずれかです。上の「テーブルが壊れる原因とチェックリスト」を上から順に確認してください。
関連記事
- Markdown 表の書き方: 配置・エスケープ・コピペできる例 — 表をゼロから書く手順をチュートリアル形式で
- CSV を Markdown テーブルに変換する方法 — Excel やスプレッドシートのデータから一発変換
- JSON を Markdown テーブルに変換する方法 — API レスポンスや配列をそのまま表化
- HTML テーブルを Markdown に変換する方法 — Web ページの
<table>をピンポイントで取り出す - GitHub README に表を入れる方法 — CSV / JSON から README 用テーブルを生成
- データフォーマット早見表 — JSON / YAML / CSV / Markdown を横断比較
- Markdown を HTML に変換する方法 — 作った表を Markdown 非対応の CMS に貼る
- HTML を Markdown に変換する方法 — Web ページや Notion エクスポートの表を取り出す