CSV はほぼあらゆるツールのデフォルト出力形式です。スプレッドシート、データベースダンプ、分析ダッシュボードはどれも CSV で書き出します。しかし README を書くとき、GitHub Issue を立てるとき、ドキュメントを作るときに必要なのは Markdown テーブルです。CSV を Markdown テーブルに手動変換するのは面倒でミスが起きやすいです。このガイドでは Markdown テーブルの書式、CSV の端末ケースの扱い、そしてオンラインで即時変換する方法を解説します。

CSV を Markdown テーブルに変換 →

Markdown テーブルの書式

Markdown テーブルは 3 つのパーツで構成されます：

| 列 A | 列 B | 列 C |
|------|------|------|
| 値 1 | 値 2 | 値 3 |
| 値 4 | 値 5 | 値 6 |

ルール：

  • 最初の行がヘッダーです。
  • 2 行目（区切り行）はダッシュ --- とオプションのコロンで構成します。
  • すべての行は同じ数のパイプ区切りセルを持つ必要があります。

列の配置

区切り行が列の揃えを制御します：

| 左揃え   | 中央揃え | 右揃え   |
|:--------|:-------:|--------:|
| テキスト | テキスト | テキスト |
構文配置
---左揃え（デフォルト）
:---左揃え（明示）
:---:中央揃え
---:右揃え

数値列には右揃えを使うと読みやすくなります。

CSV → Markdown テーブル：例

基本的な変換

入力 CSV：

名前,役割,チーム
Alice,エンジニア,プラットフォーム
Bob,デザイナー,プロダクト
Charlie,マネージャー,グロース

出力 Markdown：

| 名前    | 役割         | チーム           |
|---------|--------------|------------------|
| Alice   | エンジニア   | プラットフォーム |
| Bob     | デザイナー   | プロダクト       |
| Charlie | マネージャー | グロース         |

カンマを含むフィールド

CSV はダブルクォートで値内のカンマを処理します：

都市,説明
東京,"日本の首都、テクノロジーの中心"
大阪,"日本第二の都市、グルメの街"

変換ツールはクォートを除去し、値内のパイプ文字（|）を \| にエスケープしてテーブル構造を維持します。

数値列

数値データを持つテーブルでは、数値列を右揃えにすると見やすくなります：

商品,価格,数量
キーボード,8500,30
マウス,3200,80
ヘッドセット,12000,15

右揃えにした出力：

| 商品         |   価格 | 数量 |
|--------------|-------:|-----:|
| キーボード   |   8500 |   30 |
| マウス       |   3200 |   80 |
| ヘッドセット | 12000  |   15 |

空セル

CSV に欠損値があると Markdown テーブルでは空のセルになります：

id,名前,メール
1,Alice,[email protected]
2,Bob,
3,,[email protected]

出力：

| id | 名前  | メール            |
|----|-------|-------------------|
| 1  | Alice | [email protected] |
| 2  | Bob   |                   |
| 3  |       | [email protected] |

よくある使い方

GitHub README

GitHub は README・Wiki・Issue で Markdown テーブルをネイティブにレンダリングします。CSV を変換ツールに貼り付け、Markdown をコピーして README に貼り付けるだけです。

API ドキュメント

リクエストパラメーターやレスポンスフィールドを文書化するとき、スプレッドシートから CSV を書き出し、Markdown に変換してドキュメントに貼り付けます。手動でテーブルを整形するよりはるかに速いです。

GitHub Issue と PR

テスト結果、ベンチマーク比較、設定値をバグ報告に添付するとき、Markdown テーブルは生 CSV のコードブロックよりずっと読みやすいです。

Notion・Zenn・Qiita

Notion は Markdown 貼り付けを認識してテーブルとして変換します。Zenn と Qiita も Markdown テーブルをそのまま投稿できます。

静的ドキュメントサイト

Docusaurus・VitePress・MkDocs はすべて Markdown テーブルをレンダリングします。表データをスプレッドシートで管理し、CSV エクスポート、変換、貼り付けという流れで維持できます。

値内のパイプ文字

パイプ | は Markdown テーブルの区切り文字です。CSV の値にパイプ文字が含まれる場合、出力では \| にエスケープする必要があります：

ショートカット,操作
Cmd|Ctrl+C,コピー
Cmd|Ctrl+V,貼り付け

変換後：

| ショートカット | 操作       |
|----------------|------------|
| Cmd\|Ctrl+C    | コピー     |
| Cmd\|Ctrl+V    | 貼り付け   |

良い変換ツールはこれを自動で処理します。

コードで変換する

JavaScript

function csvToMarkdown(csv, alignRight = []) {
  const lines = csv.trim().split('\n');
  const rows = lines.map(line =>
    line.split(',').map(cell =>
      cell.trim().replace(/^"|"$/g, '').replace(/\|/g, '\\|')
    )
  );

  const headers = rows[0];
  const separator = headers.map((_, i) =>
    alignRight.includes(i) ? '---:' : '---'
  );

  const toRow = cells => '| ' + cells.join(' | ') + ' |';
  return [toRow(headers), toRow(separator), ...rows.slice(1).map(toRow)].join('\n');
}

const csv = `商品,価格\nキーボード,8500\nマウス,3200`;
console.log(csvToMarkdown(csv, [1])); // 列 1 を右揃え

Python

import csv
import io

def csv_to_markdown(csv_text, align_right=None):
    align_right = align_right or []
    reader = csv.reader(io.StringIO(csv_text.strip()))
    rows = [[cell.replace('|', '\\|') for cell in row] for row in reader]

    if not rows:
        return ''

    headers = rows[0]
    col_widths = [max(len(row[i]) for row in rows) for i in range(len(headers))]

    def fmt_row(cells):
        padded = [cells[i].ljust(col_widths[i]) for i in range(len(cells))]
        return '| ' + ' | '.join(padded) + ' |'

    sep = [('-' * w + ':') if i in align_right else '-' * w
           for i, w in enumerate(col_widths)]

    lines = [fmt_row(headers), '| ' + ' | '.join(sep) + ' |']
    lines += [fmt_row(row) for row in rows[1:]]
    return '\n'.join(lines)

csv_text = "商品,価格\nキーボード,8500\nマウス,3200"
print(csv_to_markdown(csv_text, align_right=[1]))

Markdown テーブルの制限

Markdown テーブルにはいくつかの制限があります：

  • セル結合不可：colspan・rowspan はサポートされません。複雑なレイアウトには HTML テーブルを使います。
  • 複数行セル不可：セル内の改行はテーブル構造を壊します。
  • スタイル指定不可：フォント・色・枠線はテーマが制御します。Markdown では指定できません。
  • 超幅広テーブル：列が 30 を超えたり行が数百を超えると可読性が著しく落ちます。分割するかコードブロックを検討してください。

Markdown では対応できない場合、GitHub はインライン HTML テーブルもサポートします：

<table>
  <tr><th>名前</th><th>役割</th></tr>
  <tr><td>Alice</td><td>エンジニア</td></tr>
</table>

オンライン CSV → Markdown 変換ツール

ZeroTool の CSV to Markdown 変換ツールは完全にブラウザ内で動作します。CSV を貼り付け、列の揃えを選び、Markdown 出力をコピーするだけです。ファイルのアップロード不要、アカウント登録不要。

CSV to Markdown 変換ツールを開く →