MarkdownテーブルをCSVに変換する方法と、知っておくと楽になる話

GitHubのREADMEに書いた対応表をExcelで集計したくなったり、ドキュメント内のテーブルをスプレッドシートに移したくなったり。Markdownテーブル → CSVの変換は、エンジニアをやっているとちょくちょく発生する割に、地味に面倒な作業です。

数行なら手で書き写せば済みますが、20行を超えたあたりから「これ、自動でやれないか」と考え始めるはず。この記事では、Markdownテーブルの構造をおさらいしたうえで、変換の選択肢と落とし穴を整理します。

Markdownテーブルの構造

まず変換元の構造を確認しておきます。Markdownのテーブルはこういう書式です。

| 名前 | 年齢 | 部署 |
| ---- | ---- | ---- |
| 田中 | 28   | 営業 |
| 鈴木 | 34   | 開発 |

構成要素は3種類だけです。

• 1行目 — ヘッダー行。列名をパイプ（|）で区切る
• 2行目 — 区切り行。---- や :---:（中央揃え指定）が並ぶ。テーブルであることを示す目印
• 3行目以降 — データ行

一方、同じ内容のCSVはこうなります。

名前,年齢,部署
田中,28,営業
鈴木,34,開発

見比べると分かるとおり、両者の違いは大きく3つあります。

1. 区切り文字が | か , か
2. Markdownには区切り行（---- の行）があるが、CSVにはない
3. Markdownは見た目を揃えるための余分なスペースを含むことが多い

つまり変換処理の本質は「区切り行を捨て、各セルの前後の空白を削り、パイプ区切りをカンマ区切りに置き換える」という3ステップです。

手作業での変換と、その落とし穴

エディタの置換機能や正規表現で変換する場合、ざっくりこういう手順になります。

1. 区切り行（|----|----| の行）を削除する
2. 行頭・行末のパイプを削除する
3. |（前後スペース込みのパイプ）を , に置換する
4. 残った各セルの前後の空白を削る

一見シンプルですが、実際にやってみるとハマりどころがいくつかあります。

セルの中にカンマがある場合。 「東京都,新宿区」のような値をそのままカンマ区切りにすると列がずれます。CSVの仕様では、カンマを含む値は "東京都,新宿区" のようにダブルクォートで囲む必要があります。正規表現の単純置換ではここまで面倒を見てくれません。

セルの中にエスケープされたパイプがある場合。 Markdownではセル内に \| と書くことでパイプ文字を表現できます。これを区切り文字と誤認すると、やはり列がずれます。

空セルの扱い。 | 田中 | | 営業 | のような空セルは、CSV側でも空の値として位置を保持しなければいけません。

行数が少なくて値が単純なら手作業で十分ですが、カンマや記号を含む実データでは、この細部の処理を間違えて「列がずれたCSV」が出来上がりがちです。しかも列ずれは目視で気づきにくい。

結局どう変換するのが楽か

選択肢は3つあります。

• エディタの正規表現置換 — 数回きりの単純なテーブルなら最速。ただし上記の落とし穴は自前で処理
• スクリプトを書く — PythonやJavaScriptで10行程度。定期的に同じ変換をするなら資産になる
• 変換ツールを使う — 貼り付けるだけ。カンマ・クォート処理込みで一番確実

当サイトのMarkdown → CSV変換ツールは、テーブルを貼り付けるとリアルタイムでCSVに変換します。カンマを含むセルのクォート処理や区切り行の除去も自動です。ブラウザ内で処理が完結するので、社内ドキュメントの表でも安心して使えます。

逆方向（CSV → Markdownテーブル）のツールもあるので、「Excelで整理したデータをREADMEに貼る」という逆のシーンでも使えます。個人的には、ドキュメントを書くときはCSV → Markdown、集計するときはMarkdown → CSVと、行ったり来たりすることが多いです。

まとめ

• MarkdownテーブルとCSVの違いは「区切り文字・区切り行・余白」の3点
• 変換自体は単純だが、カンマ入りセル・エスケープ・空セルの処理でずれやすい
• 数行なら手作業、繰り返すならスクリプト、確実さ重視ならツールが楽

テーブルの変換は「たまにしか発生しないが、発生すると面倒」な作業の代表格。やり方を一度押さえておくと、次に出くわしたときにサッと片付けられます。