CSV を Markdown テーブルに変換する方法

GitHub の README に表を載せたい。Issue や Pull Request の説明に集計結果を貼りたい。Notion や Obsidian に転記したい。こうした場面で必要になるのが、CSV から Markdown テーブルへの変換です。

Excel やスプレッドシートで作った表をそのままコピーしても Markdown テーブルにはならず、手書きで | を並べていくのは現実的ではありません。この記事では、Markdown テーブルの構造を確認したうえで、FormatArc を使った変換手順とハマりやすいポイントを紹介します。

Markdown テーブルの構造

GitHub Flavored Markdown（GFM）のテーブルは、パイプ記号 | で区切る形式です。

| name | email | role |
| --- | --- | --- |
| Mika | mika@example.com | admin |
| Noah | noah@example.com | viewer |

1 行目がヘッダー、2 行目が区切り線、3 行目以降がデータ行です。区切り線の : の位置で、左寄せ・中央揃え・右寄せを指定できます。

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

シンプルですが、行数が多いと手書きはつらくなります。20 行 5 列の表なら、すべての列幅を揃えながら | を打つのは現実的ではありません。

CSV から手動で変換するのが面倒な理由

数行なら手作業で書けますが、実務で使う表には次のような問題が出てきます。

• 行数が多い（README に貼る比較表が 30 行以上になることもある）
• セル内にパイプ記号 | が含まれていてエスケープが必要
• セル内に改行が入っていて Markdown テーブルに収まらない
• 列数が行ごとに揃っていない CSV をそのまま貼ると表が崩れる

特に Excel から書き出した CSV をそのまま貼ろうとして、数値の桁区切りカンマが列区切りと衝突するパターンや、改行コードの違いで表示が崩れるパターンはよくあります。

FormatArc で変換する

CSV to Markdown を使えば、貼り付けてボタンを押すだけで GFM 互換のテーブルが出力されます。

ステップ 1: ツールを開く

CSV to Markdown にアクセスします。

ステップ 2: CSV を貼り付ける

左側のエディタに CSV を貼り付けます。Excel やスプレッドシートからのコピー、あるいはテキストファイルからのコピーをそのまま使えます。1 行目がヘッダーとして扱われます。

ステップ 3: 実行ボタンを押す

実行ボタンを押すと、右側に Markdown テーブルが表示されます。

出力はそのままコピーして README や Issue に貼れる形式です。区切り線も列数も自動で揃います。

処理はすべてブラウザ内で完結するため、社内データや顧客リストを貼っても外部サーバーには送信されません。

ハマりやすいポイント

セル内のパイプ記号

セルに | が含まれていると、そのままでは列区切りと区別できません。FormatArc では自動で \| にエスケープして出力するので、貼り付け側で気にする必要はありません。

| x | y |
| --- | --- |
| foo\|bar | baz |

セル内の改行

Markdown テーブルは仕様上、セル内の改行を表現できません。FormatArc では改行を半角スペースに置換します。改行ごと別の行として表示したい場合は、もとのデータ側で <br> などの HTML タグを直接書く必要があります。

列数が揃っていないとき

ヘッダーが 3 列なのにデータ行が 4 列ある CSV では、ヘッダーの列数を基準にして 4 列目以降は切り捨てられます。逆にデータ行が短い場合は空セルでパディングされ、テーブルとして崩れない出力になります。

変換した Markdown テーブルの活用

GitHub README

API のエンドポイント一覧、サポートしているオプション、ライブラリの比較表など、README で表が必要になる場面は多くあります。CSV で管理しておけば、内容を更新するたびに表を作り直す手間が減ります。

Issue や Pull Request の説明

ベンチマーク結果やテストケース一覧を表で示すと、レビュアーが内容を追いやすくなります。スプレッドシートで集計したデータを Markdown テーブルに変換して貼るだけで済みます。

Notion・Obsidian・Zenn・Qiita

これらのツールはいずれも Markdown を採用しています。CSV で管理しているデータを Markdown テーブルに変換しておけば、ツール間で資料を移すときに整形し直す必要がありません。

まとめ

CSV から Markdown テーブルへの変換は、手書きでやろうとすると行数や列幅、エスケープ処理で時間を取られます。CSV to Markdown を使えば貼り付けて実行を押すだけで済むので、表を作るたびに手書きしている場合はぜひ一度試してみてください。

CSV の基本については CSVとは を、CSV を JSON に変換したい場合は CSV to JSON 変換ガイド を参照してください。