Markdownの表が文字列のまま表示される、列がずれる、セル内で改行・結合したい。GFMの基本構文と症状別の直し方、改行タグとHTMLの表の使い分け、プレビューで切り分ける方法を説明します。
目次(9)
Markdownの表が崩れる・表示されないときは、見出し行の直下の区切り行、見出し行と区切り行の列数、セル内の | の3点を先に確かめます。セル内の改行は <br> で書き、セルの結合はGFMの表では書けないため、HTMLの表にするか表を分けます。
原因は、単純な書き間違いだけではありません。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つのセルへ長い説明や複数段落を詰め込むほど、環境依存の問題が起きやすくなります。セルの中で行を変えたいだけなら、次の節の <br> を使います。
表は比較項目を短く整理する用途に使い、長い説明は表の下へ出す方が安定します。
原因6:書き方は合っているが、表示先がその表記法に対応していない
ここが見落とされやすい点です。
Markdownには複数の実装があります。GFMはCommonMarkを基礎にしながら、表やタスクリストなどの拡張を追加しています。
そのため、GFMでは表として表示できるMarkdownでも、別のMarkdown実装では同じように表示されないことがあります。
たとえば、GitHubで使うREADMEの最終確認はGitHub自身で行うのが確実です。逆に「Markdownの構文としてどこで崩れているか」を先に確認したいなら、汎用Viewerで一次確認してから公開先を見ると切り分けやすくなります。
一般的なプレビュー方法については、Markdownをブラウザだけでプレビューする方法でも整理しています。
セル内で改行したい・セルを結合したいとき
GFMの表には、セルの中で段落を分ける記法も、セルを結合する記法(HTMLのcolspan・rowspanにあたるもの)もありません。GFM仕様の表の節が定めているのは、セルの中でインライン要素を解析することと、列数が足りない行を空セルで補い、多いセルを無視することだけです。
セル内の改行は <br> で書く
セルの中でもインライン要素は解析されるため、インラインのHTMLである改行タグ <br> を書けば、1つのセルの中で行を変えられます。GitHubのドキュメントも、.mdファイルで改行する方法の1つに <br/> タグを挙げています。
| 項目 | 説明 |
| --- | --- |
| 手順 | 1行目<br>2行目 |
ただし、HTMLタグをそのまま出力するかどうかは表示先の設定によります。HTMLを許可していない環境では、<br> が文字として見えたり取り除かれたりすることがあります。
セルの結合は、HTMLの表にするか表を分ける
GFMの表で結合したセルを作る記法はないため、結合が必要なら表全体をHTMLの <table> で書くか、結合をやめて表を分けます。HTMLの表も、表示先がHTMLを許可しているかどうかで結果が変わります。
Markdownのまま管理したい場合は、結合したかった単位ごとに見出し付きの表を分けるか、共通する値を各行に書く方が、表示先に左右されにくくなります。
出典:GitHub Flavored Markdown Spec: Tables/GitHub Docs: Basic writing and formatting syntax(Line breaks)
症状から原因を切り分ける
表が崩れたときは、見た目からある程度原因を絞れます。
| 症状 | 最初に確認する場所 |
|---|---|
| 表全体が文字列のまま | 見出し行と区切り行、対応するMarkdown実装 |
| 列が途中からずれる | セル内の |、本文行の列数 |
| 表が途中で終わる | 空行、引用、別ブロックの開始 |
| 一部の環境だけ崩れる | GFMなどMarkdown実装の違い |
| 長文セルだけ不自然 | セル内改行、ブロック要素 |
<br> が文字のまま見える |
表示先がHTMLを許可しているか |
「表にならない」という一言でも、原因は同じではありません。まず症状を分けると、全体を書き直さずに済みます。
表の不具合を直す最小再現テスト
記事全体から表だけ抜き出し、まず次の3行で表示できるか確認します。
| 項目 | 数 |
| --- | ---: |
| A | 10 |
表示できない場合、次を順番に確かめます。
- ヘッダーと本文の間に、ハイフンを含む区切り行があるか。
- 行ごとの区切り文字が意図した列数になっているか。
- 表の途中に意図しない改行・コードフェンスがないか。
- Markdownの実装がGFM形式の表をサポートしているか。
このサンプルが表示できるのに元原稿の表だけ崩れるなら、元原稿の1行ずつを戻して変化する箇所を探します。Markdown表の構文が正しくても、最終的なCMSやチャットアプリが同じ表機能を実装しているとは限りません。原稿の構文と、表示先の対応機能は別々に確認します。
Markdown Viewerで切り分ける手順
表の原因を確認するときは、元の文書を直接何度も編集するより、問題の表だけをコピーして最小化すると分かりやすくなります。
- 問題の表だけをコピーする
- Markdown Viewerへ貼る
- 見出し・区切り行・最初の1行だけに減らす
- 表として表示されるところまで戻す
- 削った行や記号を少しずつ戻す
この方法なら、「Markdownの構文で崩れているのか」「最終的な公開先固有の問題なのか」を分けて考えられます。
公開先固有の問題とは分けて考える
Markdownそのものの表が正しく書けているのに、投稿先のエディタへ貼ると表として扱われない場合は、Markdown構文とは別の問題です。
公開先によって、Markdown表への対応状況や貼り付け時の変換方法は異なります。まずMarkdownとして表が成立しているかを確認し、その後で公開先の仕様を確認すると、原因を混同しにくくなります。