CSV を Markdown の表に変換する方法：列数・縦棒・配置

表を Markdown に貼るとき面倒なのは、区切りの行と縦棒を手で書く作業です。データを貼って一度変換すれば、そのままコミットできる表のソースになります。

Markdown の表が必要な場面

issue に再現手順の表を貼る、README にパラメータの比較を載せる、PR の説明に変更点を並べる。こうした内容は箇条書きより表のほうが読みやすくなります。ただし Excel からコピーするとタブ区切りの文字列になり、縦棒を手で足すのは遅く、ずれやすい作業です。

ドキュメントや wiki、ブログに価格表を入れる場合も同じで、すでにある表データを Markdown の記法に変えるだけです。縦棒の位置を数えながら書き直す必要がなくなり、その分を内容に使えます。

行ごとに処理し、空行は捨て、各行をタブまたはカンマで分割します。1 行目が見出しとして扱われ、以降の行が表の行になり、区切りの行は常にハイフン 3 つです。そのためデータの 1 行目は列名でなければなりません。

注意点は 3 つです。セル内に縦棒があると表の構造が壊れるため、先に別の記号へ置き換えるかエスケープが必要です。行ごとに列数が違っても補われず、足りない行はセルが欠けます。セル内の改行は解析をずらすので、先に 1 行へまとめてください。

生成される区切り行はハイフン 3 つで、既定の配置になります。Markdown はコロンで配置を指定でき、先頭にコロンで左寄せ、両側で中央、末尾で右寄せになりますが、このツールはその記法を出力しないため、変換後に手で書き換えます。

列幅は気にしなくて構いません。ソース上で列の長さが揃っていなくても、描画時に整えられるため、空白で埋める必要はありません。セルの結合、見出しのグループ化、セル内の複数行には対応しておらず、そのような表は HTML に置き換えるか分割が必要です。

表を中央寄せや右寄せにできますか？

ツール自体は配置の記号を出しませんが、Markdown は対応しています。区切り行の先頭にコロンで左寄せ、両側にコロンで中央、末尾にコロンで右寄せになります。変換後にその行を書き換えれば、多くの描画環境で反映されます。

セルに縦棒があるときはどうすればいいですか？

縦棒は列の区切り記号なので、そのまま入れると後ろが新しい列として扱われます。直前にバックスラッシュを付けてエスケープするか、HTML の実体参照に置き換えるか、変換前にスラッシュや読点へ置き換えてください。

Excel からコピーするとタブ区切りですが認識しますか？

認識します。タブとカンマの両方に対応しているため、Excel や表計算ソフトからそのままコピーしても、CSV に書き出す必要はありません。1 行目が見出しになるので、コピー時に列名を落とさないよう注意してください。