Markdownの表が崩れる原因と直し方｜区切り行のズレと見えない文字

Markdownの表がGitHubやQiita、Notionで崩れる原因は、ほとんどの場合列数のズレ・セル内の改行・パイプ記号の未エスケープの3つに集約されます。ただしこの3つを直しても崩れが直らないときは、全角文字や見えない文字の混入、あるいはそもそも使っているツールが表構文（GFM拡張）に対応していないことを疑ってください。原因ごとの見分け方と直し方を順に解説します。

Markdownの表の基本構文

まず正しい構文を確認します。Markdownの表は3行以上で構成します。

| 見出し1 | 見出し2 |
| --- | --- |
| セルA | セルB |
| セルC | セルD |

1行目がヘッダー行、2行目が区切り行（ハイフンを並べた行）、3行目以降がデータ行です。この構文はMarkdown本体の仕様には含まれておらず、GitHub Flavored Markdown（GFM）という拡張仕様で定義されています。GitHub・Qiita・Zenn・Notion・Slackなど主要なサービスはGFMに準拠していますが、すべてのMarkdownパーサーが対応しているわけではないという点が、後述する原因6につながります。

原因1：ヘッダー行と区切り行の列数が合っていない

最も多い原因です。ヘッダー行のパイプの数と、区切り行のパイプの数は完全に一致していなければなりません。

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

この例では、ヘッダー行が3列なのに区切り行が2列しかありません。多くのパーサーはこの時点で表として認識せず、生のテキストとしてそのまま表示します。表全体がプレーンテキストになって崩れているように見える場合、まずこの列数を数え直してください。

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

原因2：区切り行の書き方そのものが不正

区切り行は「ハイフンのみ」または「コロン＋ハイフン」で構成する必要があります。次のような間違いがよく起きます。

特に「全角の長音記号」は日本語入力中に変換ミスで混入しやすく、フォントによっては半角ハイフンとほぼ同じ見た目になるため、目視でのチェックが困難です。

原因3：セル内で改行している

セルの中で普通に改行すると、そこで行が終わったと解釈され、表の構造が崩れます。

| 項目 | 説明 |
| --- | --- |
| 手順 | 1つ目の作業
2つ目の作業 |

セル内で改行したい場合は、<br>タグを使います。

| 項目 | 説明 |
| --- | --- |
| 手順 | 1つ目の作業<br>2つ目の作業 |

<br>はHTMLタグですが、GFM準拠のパーサーはMarkdown中のインラインHTMLをそのまま通すため、多くの環境で問題なく表示されます。ただしMarkdownをそのままテキストとして扱うだけの環境（一部のチャットツールの下書き欄など）では<br>が文字列としてそのまま出てしまうことがあるため、投稿先で見え方を確認したほうが安全です。

原因4：パイプ記号がエスケープされていない

セルの中身に|という文字そのものを書きたい場合、そのままだと列の区切りと誤認されます。

| コマンド | 説明 |
| --- | --- |
| grep a | b | aとbのどちらかを検索 |

3列目扱いになってしまい、意図した2列の表になりません。バックスラッシュでエスケープします。

| コマンド | 説明 |
| --- | --- |
| grep a \| b | aとbのどちらかを検索 |

コマンドやパスをそのままセルに貼り付けたときに起きやすいので、コピペ後は|が含まれていないか確認してください。

見落としがちな原因：全角文字と見えない文字の混入

ここまでの4つを直しても崩れが直らない場合、目に見えない、あるいは見分けにくい文字が紛れ込んでいる可能性があります。これはMarkdownの解説記事でもあまり触れられていない実務上の落とし穴です。

全角記号の混入

区切り行や表の枠線に使う - や | が、日本語入力の変換で全角の －（全角ハイフン）や ｜（全角パイプ）に化けていることがあります。フォントによっては半角と見分けがほぼつかず、目視でのチェックでは気づけません。

| A | B |
|－－－|－－－|

見た目はほぼ区切り行に見えますが、パーサーからは認識されず、表として成立しません。IMEをオフにした状態で区切り行を打ち直すのが確実です。すでに全角文字が混ざったテキストが手元にある場合は、全角⇔半角変換ツールで記号だけを半角に一括変換すると、手作業で1文字ずつ探すより早く直せます。

コピペで紛れ込む不可視文字

WebページやPDF、Wordの文書からセルの内容をコピペすると、ゼロ幅スペース（U+200B）や改行コードの一種であるU+2028のような、画面上では何も表示されない文字が紛れ込むことがあります。これらは区切り行の中に入り込むと、ハイフンの並びを分断してしまい、パーサーが区切り行として認識できなくなります。

見た目には何の異常もないのに表だけが崩れている場合は、疑わしい行をいったん削除して手打ちで再入力してみるのが最も確実な切り分け方法です。エディタに「不可視文字を表示」する機能があれば、それを有効にして確認する方法もあります。

原因6：そもそも表構文（GFM拡張）に対応していないツールを使っている

構文がすべて正しいのに、表がそのまま| A | B |という生のテキストで表示される場合は、使っているツールがGFMのテーブル拡張に対応していない可能性があります。

Markdownという名前が付いていても、実装によって対応範囲は次のように差があります。

表はMarkdown本体の仕様（John GruberによるオリジナルのMarkdown、およびCommonMark）には含まれておらず、GitHubが独自に拡張した仕様です。そのため、「Markdown対応」と書かれたツールであっても、テーブル拡張までは実装していないケースは珍しくありません。この場合はいくら区切り行を直しても解決しないため、投稿・変換先が実際にGFMの表構文をサポートしているかを確認するのが唯一の対処法です。別のGFM準拠のエディタでいったんプレビューしてみて、正しく表になるかを試すと切り分けられます。

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

区切り行にコロンを付けると、列ごとに文字寄せを指定できます。

| 左寄せ | 中央寄せ | 右寄せ |
| :--- | :---: | ---: |
| a | b | c |

コロンの位置を間違えると、意図しない寄せになったり、パーサーによっては認識されずデフォルトの左寄せに戻ったりします。左は:が先頭のみ、右は:が末尾のみ、中央は両端という対応を覚えておくと迷いません。

まとめ

1. まずヘッダー行と区切り行の列数が一致しているかを数える
2. セル内の改行は<br>、セル内の|は\|でエスケープする
3. 直しても崩れる場合は全角記号・不可視文字の混入を疑い、区切り行を打ち直す
4. 構文が正しいのに表にならない場合は、そのツールがGFMのテーブル拡張に対応しているかを確認する
5. 寄せを指定する場合は、コロンの位置（左:先頭のみ／右:末尾のみ／中央:両端）を確認する

表の崩れは原因が1つとは限らず、複数の要因が重なっていることもあります。上から順に切り分けていけば、ほとんどのケースは解決できます。