Markdownの表が文字列のまま表示される、列がずれる、途中で崩れる原因を症状別に整理します。GFMの基本構文と、プレビューで切り分ける方法を解説します。
Markdownで表を書いたのに、表にならず文字列のまま表示されたり、列がずれたりすることがあります。
原因は、単純な書き間違いだけではありません。Markdownの表は標準Markdownのすべての環境で共通の機能ではなく、GitHub Flavored Markdown（GFM）などの拡張として実装されている場合があります。 そのため、同じ記述でも表示先によって結果が変わることがあります。
この記事では、表が崩れたときに「どこを直せばよいか」を症状ごとに切り分けます。
先に結論：まず最小の表に戻してプレビューする
表が表示されないときは、いきなり全体を書き直すより、次の3点を先に確認すると原因を絞りやすくなります。
- 見出し行の直下に区切り行があるか
- 見出し行と区切り行の列数が一致しているか
- セル内の
|をそのまま書いていないか
そのうえで、Markdownをレンダリングできる環境で表示を確認します。
oka-projectのMarkdown Viewerは、.mdファイルやMarkdownテキストをブラウザ上でプレビューできる無料・登録不要のツールです。入力内容はブラウザ内で処理し、サーバーへ送信・保存しない構成にしています。表の記述を少しずつ直しながら、Markdownとしてレンダリングされるかを切り分ける一次確認に使えます。
まずは正しく表示される最小構文を確認する
GFMの表は、見出し行、区切り行、本文行の順で書きます。
| 項目 | 状態 |
| --- | --- |
| A | 完了 |
| B | 未対応 |
GitHubのドキュメントでは、見出しの下に置く区切り行について、各列に少なくとも3つのハイフンを使う例が案内されています。GFM仕様では、区切り行にコロンを付けることで左右・中央揃えも指定できます。
| 左寄せ | 中央 | 右寄せ |
| :--- | :---: | ---: |
| A | B | C |
表が崩れたら、まず装飾や長い文章を外し、この最小形で表示できるか確認します。
原因1：見出し行と区切り行の列数が合っていない
表全体がただのテキストとして表示される場合、最初に確認したいのが列数です。
次の例では、見出しは2列なのに区切り行が1列しかありません。
| 名前 | 状態 |
| --- |
| A | 完了 |
GFM仕様では、見出し行と区切り行のセル数が一致しない場合、そのブロックは表として認識されません。
正しくは次のようにします。
| 名前 | 状態 |
| --- | --- |
| A | 完了 |
本文行の列数についてはGFMでは少し挙動が異なります。見出しよりセルが少なければ空セルが補われ、多ければ余ったセルは無視されます。
ただし、表示先によって実装差があるため、実務では本文側も列数を揃えておく方が読み間違いを減らせます。
原因2：セルの中に | をそのまま書いている
パイプ | はMarkdown表のセルを区切る記号です。
そのため、セルの本文として | を書きたい場合、そのまま入れると別のセルとして解釈されることがあります。
| 記号 | 意味 |
| --- | --- |
| | | 区切り |
GFMでは、セル内のパイプをバックスラッシュでエスケープできます。
| 記号 | 意味 |
| --- | --- |
| \| | 区切り |
コードや正規表現、コマンドの説明を表へ入れたときに崩れる場合は、セル内にパイプが含まれていないか確認します。
原因3：区切り行が表の構文になっていない
見出しの下に線らしきものがあっても、Markdownパーサーが区切り行として認識できなければ表にはなりません。
たとえば、次のような形です。
| 項目 | 状態 |
| = | = |
| A | 完了 |
GFMの区切り行はハイフンを使います。
| 項目 | 状態 |
| --- | --- |
| A | 完了 |
見た目だけで線を作るのではなく、Markdownとして決められた区切り行になっているかを確認します。
原因4：表の途中に空行や別のブロックが入っている
表の途中で急に通常の文章へ戻る場合は、空行や引用など別のブロックが混ざっていないか確認します。
GFM仕様では、表は最初の空行や別のブロック構造の開始位置で終了します。
| 項目 | 状態 |
| --- | --- |
| A | 完了 |
| B | 未対応 |
この場合、空行より後ろは同じ表として扱われません。
長い表をAIや別のエディタからコピーしたとき、途中に意図しない空行が入ることがあります。表の途中だけ崩れるなら、行の境界を確認します。
原因5：セル内で改行しようとしている
Markdownの表では、普通の段落と同じ感覚でセル内へ複数段落やブロック要素を入れられない場合があります。
GFM仕様でも、表のセルにはインライン要素が解析されますが、ブロックレベル要素は入れられません。
そのため、1つのセルへ長い説明や複数段落を詰め込むほど、環境依存の問題が起きやすくなります。
表は比較項目を短く整理する用途に使い、長い説明は表の下へ出す方が安定します。
原因6：書き方は合っているが、表示先がその表記法に対応していない
ここが見落とされやすい点です。
Markdownには複数の実装があります。GFMはCommonMarkを基礎にしながら、表やタスクリストなどの拡張を追加しています。
そのため、GFMでは表として表示できるMarkdownでも、別のMarkdown実装では同じように表示されないことがあります。
たとえば、GitHubで使うREADMEの最終確認はGitHub自身で行うのが確実です。逆に「Markdownの構文としてどこで崩れているか」を先に確認したいなら、汎用Viewerで一次確認してから公開先を見ると切り分けやすくなります。
一般的なプレビュー方法については、Markdownをブラウザだけでプレビューする方法でも整理しています。
症状から原因を切り分ける
表が崩れたときは、見た目からある程度原因を絞れます。
| 症状 | 最初に確認する場所 |
|---|---|
| 表全体が文字列のまま | 見出し行と区切り行、対応するMarkdown実装 |
| 列が途中からずれる | セル内の |、本文行の列数 |
| 表が途中で終わる | 空行、引用、別ブロックの開始 |
| 一部の環境だけ崩れる | GFMなどMarkdown実装の違い |
| 長文セルだけ不自然 | セル内改行、ブロック要素 |
「表にならない」という一言でも、原因は同じではありません。まず症状を分けると、全体を書き直さずに済みます。
Markdown Viewerで切り分ける手順
表の原因を確認するときは、元の文書を直接何度も編集するより、問題の表だけをコピーして最小化すると分かりやすくなります。
- 問題の表だけをコピーする
- Markdown Viewerへ貼る
- 見出し・区切り行・最初の1行だけに減らす
- 表として表示されるところまで戻す
- 削った行や記号を少しずつ戻す
この方法なら、「Markdownの構文で崩れているのか」「最終的な公開先固有の問題なのか」を分けて考えられます。
ただし、Markdown Viewerの表示がGitHubや特定CMSと完全に一致することを意味するものではありません。最終表示は必ず公開先でも確認します。
公開先固有の問題とは分けて考える
Markdownそのものの表が正しく書けているのに、投稿先のエディタへ貼ると表として扱われない場合は、Markdown構文とは別の問題です。
公開先によって、Markdown表への対応状況や貼り付け時の変換方法は異なります。まずMarkdownとして表が成立しているかを確認し、その後で公開先の仕様を確認すると、原因を混同しにくくなります。
まとめ
Markdownの表が表示されない場合は、まず見出し行と区切り行を確認します。特にGFMでは、この2行の列数が一致しなければ表として認識されません。
列が崩れる場合はセル内のパイプ、途中で終わる場合は空行、環境によって結果が違う場合はMarkdown実装の差を確認します。
原因が分からないときは、問題の表だけを最小構文に戻してプレビューし、少しずつ元へ戻す方法が確実です。Markdown Viewerを使えば、ブラウザ上でその切り分けを行えます。