先に診断フロー — この順で確認する
Markdown の表が壊れたとき、パーサーはエラーを出してくれません。表として認識されなければ黙ってただの段落として表示し、セルの区切りを誤認すれば黙ってずれた表を出します。エラーメッセージがない以上、原因は自分で順に潰すしかありません。
確認すべき項目は次の 5 つです。上から順に、確実に表を壊すもの・確認コストが低いものを並べています。
- ヘッダー行と区切り行の列数が一致しているか（不一致は仕様レベルで表認識を失わせる唯一の構文条件です）
- セルの中に生のパイプ
|が紛れていないか（コードスパンの中も含みます） - 表の直前に空行があるか
- そのレンダラーは GFM テーブルに対応しているか
- 書式以外の環境問題ではないか（Jupyter のセル種別、サービス側の CSS など）
切り分けの近道は、最小の表を貼ってみることです。
| A | B |
| --- | --- |
| 1 | 2 |
この 3 行が表にならないなら、原因はあなたの表ではなくレンダラーか環境です（症状 1 の後半へ）。表になるなら、あなたの表の書き方に原因があります（症状 1 から順に確認します）。
手元で GFM パーサーの解釈を確かめたいときは、Markdown to HTML に表を貼り付けると、marked ベースの GFM パーサーが出力する HTML をブラウザ内でそのまま確認できます。<table> タグが出力されていればパースは成功しています。貼り付けた内容はアップロードされません。ただしこれは GFM 系パーサーの確認であって、Notion や社内 wiki など対象サービスの挙動を完全に再現するものではない点には注意してください。
この記事はトラブルシュートに絞っています。表の正しい書き方を最初から確認したい場合は Markdown 表の書き方 を参照してください。
症状 1: 表がただの文章として表示される
パイプ区切りのテキストがそのまま 1 つの段落として表示されるケースです。パーサーが「これは表だ」と認識できなかったことを意味します。
ヘッダー行と区切り行の列数不一致
表認識を確実に失わせる構文条件はこれだけです。GFM 仕様は、区切り行の列数がヘッダー行と一致しない場合に表として扱わないことを明記しています。エラーは出ず、ただの段落に落ちます。
壊れている例です。ヘッダーは 3 列なのに区切り行が 2 列しかありません。
| 名前 | メール | 権限 |
| --- | --- |
| Mika | mika@example.com | admin |
区切り行の列数をヘッダーに合わせれば直ります。
| 名前 | メール | 権限 |
| --- | --- | --- |
| Mika | mika@example.com | admin |
数えるのはヘッダー行と区切り行の 2 行だけで構いません。データ行の列数が多い・少ないのは表認識を壊しません（症状 2 で扱います）。
表の直前に空行がない
段落の直後に空行を挟まず表を書くと、表として認識しないパーサーがあります。手元の実測（2026-06-12）では GitHub の本番レンダラー（Markdown API 経由）、marked 18.0.1、remark-gfm 4.0.1 のいずれも空行なしで表を認識しましたが、認識しない実装やサービスも存在します。空行を 1 行入れるだけで確認できる最も安い修正なので、列数の次に試してください。
ダッシュが 3 本未満なのが原因、はほぼ俗説です
検索上位の記事には「区切り行のダッシュは各列 3 本以上が必須」と書かれていることがありますが、GFM 仕様に最低本数の規定はありません。GitHub の本番レンダラー・marked 18.0.1・remark-gfm 4.0.1 のすべてで、ダッシュ 1 本（| - | - |）でも表として描画されることを実測済みです。
ややこしいのは、GitHub 公式ドキュメントが「3 本以上」と案内している一方で、仕様にはその規定がなく、実装は 1 本を受け付けるという三者の食い違いです。3 本に揃えるのは可読性のための慣習と理解しておけば十分です。ダッシュ本数を変えて直る・壊れるを探すのは時間の無駄なので、列数と空行を先に確認してください。パーサー 4 系統での実測マトリクスは Markdown 表の書き方 に掲載しています。
唯一の例外は「外側パイプを省略し、かつダッシュ 1 本」の組み合わせで、これは症状 4 で説明します。
レンダラーが GFM テーブルに対応していない
表は Markdown の中核仕様ではありません。素の CommonMark にテーブル構文の定義はなく、表は GFM の拡張機能です。拡張を入れていない CommonMark 準拠レンダラーでは、どれだけ正しく書いても表になりません。背景は CommonMark と GFM の違い にまとめています。
書式以外の環境問題もここで疑います。たとえば Jupyter Notebook ではセル種別が Code のままだと Markdown 自体が描画されません。最小表テストで表にならなかった場合は、この系統の原因です。
症状 2: 列がずれる・セルが勝手に分かれる
表にはなったが、列の位置がおかしい・1 つのセルのはずが 2 つに割れている、というケースです。
セルの中の生のパイプ
パイプ | は列区切りの記号なので、セルの値として書くと、そこで列が分割されます。次の表は「cmd1 | cmd2」というコマンド例を 1 列目に書きたかったのに、「cmd1」と「cmd2」が別のセルに割れ、ヘッダーの列数（2 列）を超えた「パイプで連結」は黙って切り捨てられます。
| コマンド | 意味 |
| --- | --- |
| cmd1 | cmd2 | パイプで連結 |
\|（バックスラッシュエスケープ）か |（HTML 数値文字参照）に置き換えれば 1 つのセルに収まります。
| コマンド | 意味 |
| --- | --- |
| cmd1 \| cmd2 | パイプで連結 |
コードスパンの中のパイプも保護されない
直感に反しますが、バッククォートで囲んでもパイプは保護されません。テーブルのパース（セル分割）はインライン要素の解釈より先に行われるためです。
| コマンド | 意味 |
| --- | --- |
| `a | b` | コードスパンのつもり |
この行は GitHub の本番レンダラー・marked・remark-gfm のすべてで「`a」と「b`」の 2 セルに割れます（2026-06-12 実測）。バッククォートも対にならず、生のまま表示されます。
直し方はコードスパンの中でもバックスラッシュを使うことです。
`a \| b`のように、コードスパン内でも\|と書きます。GitHub・marked・remark-gfm のすべてでa | bのコードとして正しく描画されることを実測済みです|はコードスパンの中では使えません。コードスパン内は文字参照が展開されないため、|という 6 文字がそのまま表示されます- 整理すると、通常のセル内テキストでは
\|と|の両方が使え、コードスパン内では\|だけが使えます
データ行の列数過不足は「ずれ」になる
データ行の列数がヘッダーと違っても表は壊れませんが、見た目のずれとして現れます。実測では、列が足りない行は空セルで補完され、多い行は超過分が黙って捨てられます。「最後の列の値が消えた」ように見えるときは、その行のどこかに余分なパイプ（= 余分な列）が紛れていないかを確認してください。
セルの値にパイプや改行を含むデータを手作業でエスケープし続けるのは消耗します。元データが CSV やスプレッドシートにあるなら、CSV to Markdown に貼り付ければ、列数の整合とパイプのエスケープをツール側で処理した表が得られます。
症状 3: セル内で改行すると表が崩れる
Markdown のテーブル構文に、セル内改行の記法はありません。セルの途中で Enter を押すと、そこから先は新しい行として解釈され、表が途切れるか別の行にずれます。
回避策はセル内に HTML の <br> タグを直接書くことです。
| 項目 | 補足 |
| --- | --- |
| 設定 A | 1 行目<br>2 行目 |
ただし <br> は Markdown の構文ではなく生 HTML の回避策なので、レンダラーが HTML を無効化・サニタイズしている環境では効きません。その場合はセル内改行をあきらめて文を分けるか、行を分割するのが現実的です。エスケープと改行の対応表は GFM テーブル チートシート にまとめています。
症状 4: GitHub では表示されるのに、別の場所では崩れる
同じ Markdown でもパーサーが違えば結果は変わります。実測で確認できた代表的な差異が「外側パイプの省略 + ダッシュ 1 本」の組み合わせです。
A | B
- | -
1 | 2
区切り行の行頭が - （ハイフン + スペース）で始まるため、これをリスト記法として解釈するかどうかでパーサーの挙動が分かれます。GitHub と remark-gfm は表とみなさずリストとして処理し、marked は表として描画します（2026-06-12 実測）。外側パイプを省略する書き方を使うなら、ダッシュは 2 本以上にしてください。行頭と行末にパイプを付けておけば、この問題自体が起きません。
「手元のプレビューでは表示されるのに投稿先で崩れる」という症状は、たいていこの種のパーサー差か、症状 1 で挙げた GFM 対応の有無です。投稿先がどの記法に対応しているかは、最小表テストと Markdown to HTML での HTML 出力確認を組み合わせると切り分けられます。プラットフォーム別の対応差（Notion が配置コロンや <br> を無視する、など）は Markdown 表の書き方 のプラットフォーム表を参照してください。
直すより作り直したほうが早いとき
壊れた表のパイプを 1 本ずつ数えて直すより、元データから表を再生成したほうが早いケースは多いです。元の値が CSV・Excel・スプレッドシートにあるなら、次の手順で数十秒で終わります。
- 元データを CSV としてコピーします（Excel やスプレッドシートの範囲コピーでも構いません）
- CSV to Markdown に貼り付けます
- 出力された Markdown の表をコピーして、壊れた表と差し替えます
列数の整合・パイプのエスケープ・区切り行の生成はすべてツール側で処理されます。変換はブラウザ内で完結し、データはどこにも送信されないため、社内データを含む表でも安心して使えます。CSV からの変換手順の詳細は CSV から Markdown 表への変換ガイド、変換後の表を HTML にする方法は Markdown を HTML に変換する方法 を参照してください。
まとめ — 診断の順序だけ覚えて帰る
表が表示されないときは、ヘッダー行と区切り行の列数、表の直前の空行、レンダラーの GFM 対応の順に確認します。列がずれるときは、セル内の生のパイプ（コードスパンの中も含めて \| でエスケープ）とデータ行の列数を疑います。ダッシュの本数は、外側パイプ省略との組み合わせを除けば原因になりません。
診断には Markdown to HTML で HTML 出力を確認するのが近道で、修復には CSV to Markdown での再生成が確実です。どちらもブラウザ内で完結します。
関連記事
- Markdown 表の書き方 — 構文の基礎とパーサー 4 系統の実測マトリクス
- GFM テーブル チートシート — 配置・エスケープ・改行のリファレンス
- CommonMark と GFM の違い — 表が「拡張機能」である背景
- CSV から Markdown 表への変換ガイド — 再生成ルートの詳細手順
- Markdown を HTML に変換する方法 — レンダリング確認に使う変換の仕組み