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

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

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

すぐに変換したい場合は、CSV to Markdown 変換ツール に CSV を貼り付けて実行ボタンを押すだけで、GitHub 互換の Markdown テーブルが手に入ります。記法やハマりどころを先に把握したい場合は、このまま読み進めてください。

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 をそのまま貼ろうとして、数値の桁区切りカンマが列区切りと衝突するパターンや、改行コードの違いで表示が崩れるパターンはよくあります。

変換手法の比較

CSV を Markdown テーブルにする方法はいくつかあります。扱うデータ量や環境によって向き不向きが分かれます。

CLI はパイプライン処理に組み込みやすい一方、インストールと実行環境が要ります。手書きは数行なら速いですが、行数が増えると破綻します。ブラウザツールはセットアップ不要で、貼り付けたデータはサーバーに送信されず、パイプのエスケープも自動です。機密を含む 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 テーブルに変換しておけば、ツール間で資料を移すときに整形し直す必要がありません。

LLM のコンテキスト

ChatGPT・Claude・Gemini に表を渡すときは、生の HTML よりも Markdown のほうが向いています。トークン消費が少なく、抽出精度も高くなるためです。実測したトークン数と表の抽出精度の比較は LLM に渡すなら Markdown か HTML か を参照してください。

レンダラ別の配置 (alignment) 対応

GFM の配置構文 (:--- 左寄せ、:---: 中央寄せ、---: 右寄せ) は開発者向けプラットフォームではほぼ通用しますが、消費者向けの投稿ツールでは無視されたり部分対応に留まったりします。表の配置が下流で崩れているときは、まずこのマトリクスで確認してください。根拠列が「公式資料」の行は各プラットフォームの公開仕様・ドキュメントに基づきます。「報告ベース」の行は広く報告されている挙動で、当サイトで個別再検証はしていないため、重要な文書では 2 行程度のサンプル表を対象プラットフォームに貼って確認してから使ってください。

セル結合や複雑なレイアウトが必要な場合は、Markdown の中に生の HTML <table> を埋め込むのが現実解です。多くのレンダラはそのまま受け付けます。

文字エンコーディングと区切り文字の自動判定

CSV は単一のフォーマットではなく、エンコーディング (UTF-8、UTF-8 BOM 付き、Shift_JIS、Windows-1252、ISO-8859-1) と区切り文字 (カンマ、セミコロン、タブ、パイプ) で大きく挙動が変わります。押さえるべきは 2 点です。

• エンコーディング — CSV to Markdown は貼り付け方式なので、ブラウザがすでに復号した結果を扱います。UTF-8 (BOM 有無問わず) であれば、最近のエディタで開いてコピーすれば動きます。Shift_JIS や Windows-1252 のファイルは、まず正しいエンコーディングで開いてからコピーしてください (VS Code は「エンコーディングを指定して再度開く」、Excel は「データ → テキストファイル」)。エンコーディング指定を間違えると、非 ASCII 文字は文字化けして届きます。
• 区切り文字 — ツールは ,・;・\t・| を自動判定します。ヨーロッパ圏のロケールは小数点記号にカンマを使うため、CSV の区切りが ; になっていることがあります。; 区切りでもそのまま貼って動きます。同一ファイル内で区切りが混在しているような曖昧なケースは、ソース側で区切り文字を統一して書き出してください。

よくある質問

Excel から列を CSV 保存せずに直接貼り付けできますか?

できます。Excel や Google スプレッドシートで範囲をコピーすると、クリップボードに乗るのは CSV ではなくタブ区切り (TSV) のテキストです。CSV to Markdown はタブ区切りを自動判定するので、貼って実行で完結します。詳しい手順は Excel・スプレッドシート → Markdown テーブル変換 を参照してください。

FormatArc は CSV をサーバーにアップロードしますか?

しません。変換処理は開いているブラウザタブ内で JavaScript として実行されるだけで、FormatArc にも第三者のサーバーにも送信されません。顧客データ、財務指標、NDA や社内規程対象の内容を扱う場合、貼り付け方式の変換だけがローカルスクリプトを使わずに済む安全な選択肢です。ツール種別ごとのプライバシー比較は オンライン変換ツールの安全性は？ で詳述しています。

GitHub では表示されるのに別の場所で崩れます

GFM の配置構文やパイプテーブル記法に対応していないレンダラに当たっている可能性が高いです (Notion は配置指定を無視します。CommonMark のみ対応の CMS Markdown レンダラはパイプテーブル自体を解釈しません)。上記マトリクスで確認するか、パイプテーブルを扱えないプラットフォーム向けには Markdown to HTML で HTML に変換しておくと安全です。

セル内の | はどうエスケープしますか?

\| (バックスラッシュ + パイプ) を使います。FormatArc の変換ツールは貼り付けた CSV にパイプ文字が含まれていれば自動で処理します。貼り付け後に表が崩れる場合は Markdown テーブルが表示されないときの対処 を参照してください。

貼り付け可能なサイズの上限はありますか?

ブラウザタブのメモリに収まる範囲なら制限はありません。ツール内で動いている変換コードそのものを計測したところ（scripts/benchmarks/csv-to-markdown-throughput/、2026-07-13 に Apple M5 Pro + Node で warm 7 回の中央値を測定）、10,000 行の CSV は約 7 ミリ秒、50,000 行は約 36 ミリ秒、100,000 行（約 5 MB）でも約 75 ミリ秒で変換できました。ブラウザでは端末により変動しますが、変換処理自体がボトルネックになることはまずありません。数百 MB 級の巨大な CSV を扱うなら、タブに貼るより formatarc npm パッケージ でローカルスクリプトを動かす方が現実的です。

まとめ

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

生成した Markdown テーブルをさらに細かく整えたい場合（配置指定、パイプのエスケープ、改行の扱い、GFM の細かい注意点など）は Markdown 表の書き方: 配置・エスケープ・コピペできる例 を参照してください。GFM テーブルの記法を一覧で確認したい場合は GFM テーブル チートシート も便利です。

CSV の基本については CSVとは を、CSV を JSON に変換したい場合は CSV to JSON 変換ガイド を参照してください。Excel や Google スプレッドシートの表を CSV を経由せず直接コピーして変換したい場合は Excel・スプレッドシートを Markdown テーブルに変換する方法 を参照してください。ソースが CSV ではなく HTML の場合（Web ページの表や CMS からのエクスポートなど）は HTML を Markdown に変換する方法 を参照してください。生成した Markdown テーブルをさらに HTML に変換して Markdown 非対応の CMS や HTML メールに埋め込みたい場合は Markdown を HTML に変換する方法 も合わせてどうぞ。ブラウザのツールバーから同じ変換を呼び出したい場合は FormatArc Chrome 拡張の使い方 も便利です。