TL;DR — GFM テーブル早見表
- 表は「ヘッダー行 / 区切り行（
---を 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 つ以上、行頭行末のパイプは省略可です。
記法:
| 名前 | 権限 |
| --- | --- |
| 田中 | 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 行目 |
画像はセルに入れられますが、表が縦に伸びて読みにくくなりがちなのでサイズの小さいアイコン程度に留めるのが現実的です。
パイプ・特殊文字のエスケープ早見表
セルに | をそのまま書くと列区切りと誤認されてテーブルが崩れます。安全な書き方は 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 に変換する方法。
処理はすべてブラウザ内で完結するので、社内データや顧客リストを貼っても外部サーバーには送信されません。登録もアップロードも不要です。
Markdown 表で無理なこと — HTML に切り替える目安
次のような表は GFM テーブルでは表現できません。Markdown の中に HTML の <table> を直接書く方法に切り替えます。
- セルの行結合・列結合（
rowspan/colspan）が必要 - セル内に箇条書きや複数段落、コードブロックを入れたい
- 列幅をピクセルや割合で固定したい
- 表内に見出しや別の表をネストしたい
ただし GitHub などはセキュリティ上の理由でテーブル内の HTML を制限していて、<br> は通っても <span style="..."> のようなインラインスタイルは無視されます。色やフォントサイズの変更はできないと考えてください。
CommonMark とテーブルの関係
素の CommonMark にはテーブル構文の定義がありません。パイプ区切りのテーブルは GitHub Flavored Markdown 仕様の Tables (extension) セクション で定義された GFM の拡張機能です。CommonMark のみを厳密に実装し拡張を取り込まないレンダラーでは、| col | がそのまま文字列として表示され、テーブルにはなりません。お使いのツールが「GFM 互換」かどうかは、まず簡単な表を 1 つ書いてみて確認するのが早いです。
よくある質問
最小の Markdown 表はどう書きますか？
ヘッダー行 1 行、区切り行 1 行、データ行 1 行の合計 3 行が最小です。| key | value | の下に | --- | --- |、その下に | name | FormatArc | のように書きます。区切り行のハイフンは各列 3 つ以上必要です。
\| と | はどちらを使えばいいですか？
まずはバックスラッシュエスケープ \| を使ってください。GitHub の公式ドキュメントでも明示されており、主要な GFM レンダラーで動きます。レンダラーが \| を正しく扱えなかったり、エディタ間でコピペすると壊れる場合のフォールバックとして | を使います。
セル内で文字色やフォントサイズを変えられますか？
GFM テーブルだけでは変えられません。GitHub などはテーブル内の <span style="..."> のようなインラインスタイルを無視するため、色やサイズの変更は反映されません。装飾が必須なら表ごと外側に出して HTML を使うか、別の見せ方を検討してください。
列幅の目安はありますか？
Markdown には列幅を指定する記法がなく、レンダリング時に内容に応じて自動調整されます。実務上は、README やドキュメントを PC とモバイルの両方で読む想定なら列数を 5〜6 列以内に抑えるのが目安です。それを超えると GitHub 上で水平スクロールが発生し読みにくくなります。
セルの結合（rowspan / colspan）はできますか？
GFM テーブルではできません。セル結合が必要な表は Markdown の中に HTML の <table> を直接書きます。ただし GitHub などは一部の HTML 属性を制限するため、複雑なレイアウトは事前に表示を確認してください。
表が表示されず | col | のまま出ます。なぜですか？
主な原因は、表の前後に空行がない、区切り行のハイフンが 3 つ未満、ヘッダー行がない、列数が揃っていない、レンダラーが GFM テーブル拡張に対応していない（純 CommonMark 実装）のいずれかです。上の「テーブルが壊れる原因とチェックリスト」を上から順に確認してください。
関連記事
- Markdown 表の書き方: 配置・エスケープ・コピペできる例 — 表をゼロから書く手順をチュートリアル形式で
- CSV を Markdown テーブルに変換する方法 — Excel やスプレッドシートのデータから一発変換
- GitHub README に表を入れる方法 — CSV / JSON から README 用テーブルを生成
- Markdown を HTML に変換する方法 — 作った表を Markdown 非対応の CMS に貼る
- HTML を Markdown に変換する方法 — Web ページや Notion エクスポートの表を取り出す