GitHub README に表を入れる方法 — CSV/JSON から Markdown テーブルを自動生成
GitHub の README にきれいな表を載せる方法を解説します。CSV や JSON データから Markdown テーブルを自動生成する手順、GFM 固有の注意点、実務での活用パターンを紹介します。
目次
README に表を入れたいなら、CSV を CSV to Markdown に貼り付けて実行するのが最も速い方法です。ブラウザだけで GFM 互換のテーブルが生成されるので、そのまま README にコピーできます。
この記事では README にテーブルを入れるべき場面、CSV や JSON からの自動生成手順、GitHub Flavored Markdown（GFM）固有の注意点をまとめています。
README に表が必要な場面
README にテキストだけで情報を並べると、行数が増えるにつれて読みにくくなります。次のような情報はテーブルで整理するほうが伝わります。
- API エンドポイントの一覧（パス、メソッド、説明）
- 対応バージョンやプラットフォームの対応表
- 機能比較（自プロジェクトと競合、あるいはプラン別の機能差）
- コマンドラインオプションのリファレンス
- 環境変数の一覧と初期値
こうした情報を箇条書きで並べると行数が膨れ上がり、列方向の比較ができません。テーブルにすれば列を横断して違いを確認できるため、README を読む人の負担が減ります。
Markdown テーブルの基本構文
GFM のテーブルはパイプ記号 | で列を区切ります。
| コマンド | 説明 |
| --- | --- |
| install | 依存パッケージをインストール |
| build | 本番用にビルド |
| test | テストを実行 |
1 行目がヘッダー、2 行目が区切り線、3 行目以降がデータです。区切り線に : を付けると列の配置を変更できます（:--- で左寄せ、:---: で中央、---: で右寄せ）。
構文の詳細は Markdown テーブルの書き方で掘り下げています。
CSV から README 用テーブルを生成する
スプレッドシートや CSV ファイルからテーブルを作る場合は CSV to Markdown を使います。
- CSV to Markdown を開く
- 左のエディタに CSV を貼り付ける（Excel やスプレッドシートからのコピーでも可）
- 実行ボタンを押す
- 右側に出力された Markdown テーブルをコピーして README に貼る
処理はブラウザ内で完結するため、社内データを貼っても外部に送信されません。変換の仕組みやエッジケースについては CSV を Markdown テーブルに変換する方法も参照してください。
JSON データからテーブルを作る
API レスポンスやログなど、手元のデータが JSON 形式の場合もあります。JSON をそのまま Markdown テーブルにするには、一度 CSV を経由するのが確実です。
手順
- JSON Formatter で JSON を整形し、構造を確認する
- JSON の配列部分を CSV に変換する（各オブジェクトのキーが列名、値が各行のセルになる）
- CSV を CSV to Markdown に貼り付けてテーブルを生成する
たとえば次のような JSON があるとします。
[
{ "name": "Node.js", "version": "20.x", "status": "LTS" },
{ "name": "Node.js", "version": "22.x", "status": "Current" }
]
これを CSV にすると次のようになります。
name,version,status
Node.js,20.x,LTS
Node.js,22.x,Current
この CSV を CSV to Markdown に渡せば、README に貼れるテーブルが出力されます。
GFM テーブル固有の注意点
GitHub の Markdown レンダラーには、一般的な Markdown エディタと異なる挙動がいくつかあります。
HTML の混在制限
GitHub はセキュリティ上の理由でテーブル内の HTML タグを制限しています。<br> はセル内改行として使えますが、<span style="..."> のようなインラインスタイルは無視されます。色やフォントサイズの変更はできないと考えてください。
列の配置指定
区切り線に : を付ける配置指定は GitHub 上で正しく動作します。数値列を右寄せにするとバージョン番号や価格の一覧が読みやすくなります。
| プラン | 月額 |
| :--- | ---: |
| Free | $0 |
| Pro | $10 |
長いテーブルの折り返し
列数が多いテーブルは GitHub 上で水平スクロールが発生します。README を PC とモバイルの両方で読む想定なら、列数を 5〜6 列以内に抑えるか、テーブルを分割するのが実用的です。
FAQ
Q: README のテーブルをスプレッドシートで管理できますか？
はい。スプレッドシートで内容を管理し、更新のたびに CSV をエクスポートして CSV to Markdown で変換すれば、常に最新のテーブルを README に反映できます。
Q: テーブルのセルにリンクを入れられますか？
入れられます。セル内に [テキスト](URL) の形式で Markdown リンクを記述すれば、GitHub 上でクリック可能なリンクになります。
Q: セル内で改行したい場合はどうしますか？
GFM テーブルの仕様上、セル内の改行は直接表現できません。<br> タグを使えば GitHub 上で改行として描画されます。
まとめ
README に表を入れると情報の視認性が大きく上がります。手書きでパイプを並べるのは数行ならまだしも、行数が増えると現実的ではありません。CSV to Markdown を使えば CSV を貼り付けて実行するだけでテーブルが生成されるので、README を更新するたびに手作業で整形する必要がなくなります。