Markdown 表の書き方: 配置・エスケープ・コピペできる例

まず結論から

Markdown のテーブルはパイプ記号 | とハイフン - だけで書けます。

| 名前 | メール | 権限 |
| --- | --- | --- |
| 田中 | tanaka@example.com | admin |
| 鈴木 | suzuki@example.com | viewer |

手書きが面倒なら CSV to Markdown に CSV を貼り付ければ一瞬で変換できます。以下で構文を詳しく見ていきます。

基本構文 — パイプとハイフン

Markdown テーブルは 3 つのパーツで構成されます。

1. ヘッダー行 — 列名をパイプ | で区切る
2. 区切り行 — ハイフン - を並べてヘッダーとデータを分離する（3 つ並べるのが慣習）
3. データ行 — 各セルをパイプで区切る

| 項目 | 値 |
| --- | --- |
| CPU | Apple M4 |
| RAM | 16 GB |

行頭と行末のパイプは省略できますが、可読性のために付けるのが一般的です。列ごとの幅を揃える必要はありません。レンダリング時に自動で調整されます。

パイプと区切り行の構造

パイプ記号 | は列を区切る記号です。区切り行（ヘッダー区切り、ダッシュ行とも呼ばれます）はハイフン -（ダッシュとも呼びます）で構成され、ヘッダーとデータの境界をレンダラーに伝えます。

パイプとダッシュについて押さえておくべきルールは次のとおりです。

• 1 列あたりダッシュ 3 個（---）は慣習であって、パーサーのルールではありません。GFM 仕様に最低本数の規定はなく、-- でも - 1 個でも GFM レンダラーはテーブルとして描画します（marked 18.0.1 / remark-gfm 4.0.1 で検証済み）。3 個に揃えるのは可読性のためです
• 実際にテーブルを壊すのは、ヘッダー行と区切り行の列数不一致です。GFM 仕様に明記されているとおり、列数が一致しないとテーブルとして認識されません
• 行頭と行末のパイプは省略可能ですが、可読性のために付けるのが一般的です。| A | B | も A | B も同じように描画されます
• 配置コロン（:---、:---:、---:）を置けるのは区切り行だけです。データ行には書きません
• GFM ではヘッダー行が必須です。CommonMark のコア仕様にはテーブル定義そのものがないため、ヘッダーなしテーブルは独自拡張でしか存在しません

テーブルがレンダリングされない場合、まず確認すべきはヘッダー行と区切り行の列数です。ここが不一致だとテーブルとして一切認識されません。次に多い原因はテーブル前の空行欠落で、ダッシュの本数が原因になることはまずありません。

配置の指定 — 左寄せ・中央・右寄せ

区切り行にコロン : を加えると列の配置を制御できます。

| 商品 | 数量 | 単価 |
| :--- | :---: | ---: |
| りんご | 3 | 120 |
| みかん | 10 | 80 |

数値列を右寄せにすると桁が揃って読みやすくなります。

GFM（GitHub Flavored Markdown）での扱い

GitHub、GitLab、Zenn、Qiita、Notion、Obsidian など主要なプラットフォームは GitHub Flavored Markdown（GFM）のテーブル構文をサポートしています。上で紹介した構文はそのまま使えます。

GFM のテーブルで覚えておくと便利な点をまとめます。

• ヘッダー行は必須。ヘッダーなしのテーブルは GFM では作れない
• 区切り行のハイフンは 3 つ（---）並べるのが慣習。仕様上はそれ未満でも有効
• セル内でインラインの書式（コード、リンク、取り消し線など）が使える
• テーブルの前後に空行を入れないとパーサーがテーブルとして認識しない場合がある

プラットフォーム別のパイプテーブル対応

テーブルの 3 つの基本要素、つまりパイプ | によるテーブル、区切り行でのコロン配置（:---）、セル内改行用の <br> は、プラットフォームによって対応状況が異なります。次の表に各プラットフォームの挙動をまとめ、その下に個別の注記を記載します。

表に関する注記です。

• GitHub は GitHub Flavored Markdown 仕様の Tables (extension) セクション に従い、パイプテーブルと区切り行でのコロン配置を定義しています。セルはインラインコンテンツとして解析されるため、<br> のようなインラインの生 HTML が許可され、GitHub はそれをセル内改行として描画します。
• GitLab Flavored Markdown も同じパイプテーブルと配置構文をドキュメント化しており、セル内で複数行を強制するために <br> タグを使えると公式ドキュメントに明記しています。
• Obsidian はドキュメント化されたテーブル構文でパイプテーブルとコロン配置をサポートしており、実際に <br> タグをセル内改行として描画します。
• Notion はパイプテーブルをインポートまたは貼り付けできますが、GFM として描画する代わりに独自のテーブルブロックに変換します。Notion のテーブルには列ごとの配置がないため、配置コロン（:---）は見た目に影響せず、セル内の <br> も改行として描画されません。

具体的なルールは GitHub Flavored Markdown 仕様の Tables (extension) セクション で定義されています。素の CommonMark にはテーブル構文の定義がないため、テーブルは技術的には GFM の拡張機能です。CommonMark のみを厳密に実装し拡張を取り込まないレンダラーでは、テーブルとして表示されません。CommonMark と GFM の差分全体は CommonMark と GFM の違い、配置・エスケープ・改行など GFM テーブルの記法をまとめて確認したい場合は GFM テーブル チートシート を参照してください。

パイプと特殊文字のエスケープ

セルの中にパイプ | をそのまま書くと列区切りと誤認されてテーブルが崩れます。安全に書く方法は 2 つあります。

| コマンド | 意味 |
| --- | --- |
| cmd1 \| cmd2 | バックスラッシュでエスケープ |
| cmd1 | cmd2 | HTML エンティティで記述 |

• \|（バックスラッシュエスケープ）は GitHub、GitLab、Notion、Obsidian、Zenn、Qiita など主要な GFM レンダラーで動作します
• |（HTML 数値文字参照）はレンダラーが \| を正しく扱えない場合のフォールバックとして安全で、エディタ間でコピペしても壊れにくいのが利点です

セル内でバックスラッシュ自体を表示したい場合は \\ と書きます。改行なしの空白を入れたい場合は   を使います。

よくある落とし穴

セル内の改行

Markdown テーブルの仕様上、セル内で改行はできません。どうしても改行を入れたい場合は HTML タグ <br> を直接書く方法がありますが、プラットフォームによってはサポートされていません。

空セル

セルを空にしたいときはパイプの間にスペースだけ入れます。パイプを連続で書いても問題ありませんが、スペースを挟むほうが読みやすくなります。

| A | B | C |
| --- | --- | --- |
| 1 | | 3 |

列数の不一致

ヘッダーが 3 列なのにデータ行が 2 列しかない場合、ほとんどのパーサーは不足分を空セルとして処理します。逆にデータ行が多い場合は切り捨てられます。列数は揃えておくのが安全です。

大量データなら CSV から自動生成

5 行程度なら手書きで十分ですが、20 行を超えるデータや列数が多い表は手作業だと時間がかかります。Excel やスプレッドシートのデータを CSV としてコピーし CSV to Markdown に貼り付ければ、パイプの整列やエスケープ処理を気にせず一発で変換できます。

CSV からの変換手順を詳しく知りたい場合は CSV を Markdown テーブルに変換する方法 を参照してください。変換した Markdown テーブルをさらに HTML に変換したい場合は Markdown を HTML に変換する方法 もあわせてどうぞ。既存の HTML から Markdown テーブルを取り出したい場合（コピーした Web ページや Notion エクスポート、CMS のダンプなど）は HTML を Markdown に変換する方法 を参照してください。

よくある質問

Markdown テーブルにヘッダーなしの表は作れますか？

GFM ではヘッダー行が必須です。ヘッダーが不要な場合でも空のヘッダー行と区切り行を書く必要があります。

セルの中にリンクや画像を入れられますか？

インライン Markdown（[テキスト](URL) や ![alt](画像URL)）はセル内で使えます。ただしテーブルが横に長くなりすぎると可読性が落ちるため、リンクのみに留めておくのが現実的です。

テーブルの列幅を指定できますか？

Markdown の仕様には列幅の指定方法がありません。レンダリング時に内容に応じて自動調整されます。細かく制御したい場合は HTML の <table> を使う必要があります。

まとめ

Markdown テーブルの構文はシンプルで、パイプとハイフンさえ覚えれば手軽に表を作れます。配置の指定やエスケープなど細かいルールもありますが、基本を押さえておけば困ることはありません。

行数が多いデータを扱うときは CSV to Markdown で CSV を貼り付けるだけの変換がおすすめです。手書きの手間を省いて正確な Markdown テーブルを作成できます。

関連記事

• GFM テーブル チートシート — 配置・エスケープ・改行の早見表
• GitHub README に表を埋め込む方法 — 実践的な README ユースケース
• CommonMark と GFM の違い — テーブルを含む仕様差分の全体像