README に表を入れたいなら、CSV を CSV to Markdown に貼り付けて実行するのが最も速い方法です。ブラウザだけで GFM 互換のテーブルが生成されるので、そのまま README にコピーできます。
この記事では README にテーブルを入れるべき場面、CSV や JSON からの自動生成手順、GitHub Flavored Markdown（GFM）固有の注意点をまとめています。
README に表が必要な場面
README にテキストだけで情報を並べると、行数が増えるにつれて読みにくくなります。次のような情報はテーブルで整理するほうが伝わります。
- API エンドポイントの一覧（パス、メソッド、説明）
- 対応バージョンやプラットフォームの対応表
- 機能比較（自プロジェクトと競合、あるいはプラン別の機能差）
- コマンドラインオプションのリファレンス
- 環境変数の一覧と初期値
こうした情報を箇条書きで並べると行数が膨れ上がり、列方向の比較ができません。テーブルにすれば列を横断して違いを確認できるため、README を読む人の負担が減ります。
実際の README で使うテーブルの例
上で挙げた 5 つの用途は抽象的なので、そのまま README に貼って使える具体例を 3 つ並べます。
CLI オプションの一覧 — フラグが増えてきたら --help を貼るより表のほうが読みやすくなります。
| フラグ | デフォルト | 説明 |
| :--- | :--- | :--- |
| `--port` | `3000` | 待ち受けポート |
| `--host` | `0.0.0.0` | バインドアドレス |
| `--log-level` | `info` | `debug` / `info` / `warn` / `error` |
バージョン対応マトリクス — README で一番よく読まれるパートで、対応ランタイムを表で示すと一目で把握できます。
| ランタイム | 最小 | 検証済み | 状態 |
| :--- | ---: | ---: | :--- |
| Node.js | 18.x | 22.x | LTS 対応 |
| Bun | 1.0 | 1.1 | ベストエフォート |
| Deno | 1.40 | 2.0 | コミュニティ |
競合との機能比較 — 「なぜこのライブラリを使うのか」セクションで頻出します。
| 機能 | このプロジェクト | 競合 A | 競合 B |
| :--- | :---: | :---: | :---: |
| 依存ゼロ | ✅ | ❌ | ✅ |
| TypeScript 型 | ✅ | ✅ | ❌ |
| ブラウザ動作 | ✅ | ❌ | ❌ |
どの例も 3〜4 行 × 3〜4 列に抑えてあるのは意図的で、GitHub 上のモバイル表示でも水平スクロールが出ず、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 / YAML / CSV / Markdown のどの形式でデータを管理するか迷う場合は、JSON・YAML・CSV・Markdown 比較チートシートで 4 形式の使い分けを整理しています。
ブラウザを開かずターミナルで一括生成したい場合は、formatarc npm の cat users.csv | formatarc csv-to-markdown でも同じ GFM テーブルを出力できます。CI で README を自動更新する用途にも組み込めます。
JSON データからテーブルを作る
API レスポンスやログなど、手元のデータが JSON 形式の場合もあります。JSON をそのまま Markdown テーブルにするには、一度 CSV を経由するのが確実です。
配列やネスト、API レスポンスを含む JSON の表化をより詳しく知りたい場合は JSON を Markdown テーブルに変換する方法 を参照してください。
手順
- 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 に貼れるテーブルが出力されます。
README テーブルで陥りがちなミス
README のテーブルが「壊れた」原因はだいたい 4 つに集約されます。どれに引っかかったかが分かれば、Markdown ソースを長時間二分探索する必要がなくなります。先に 1 つ整理しておくと、GFM 仕様のセクション 4.10別タブで開きます は区切り行を「ハイフン (-) のみ、任意で先頭または末尾にコロン (:) を置いたセル」と定義しているだけで、ハイフンの最小個数は規定していません。テーブルの直前に空行が必要という規定もありません。
列数が揃っていない
区切り行が列数を確定させるため、それより多いセルがある行は超過分が無言で捨てられ、少ない行は空セルが補われます。
| name | role |
| --- | --- |
| Alice | Engineer | LA ← 余ったセルは無言で破棄される
| Bob ← セルが足りないと空欄で描画される
GitHub は警告を出しません。テーブルの右列が原因不明で空になっているなら、まずその行のパイプ数を数えてみてください。
区切り行が欠けている・形が崩れている
ブロックをテーブルに変えているのは区切り行なので、ここを外すと「テーブルにならない」という形で失敗します。効いているのはハイフンの本数ではなく列数です。
| name | role |
| --- | ← ヘッダー 2 列に対して区切りが 1 列。どのパーサでもテーブルにならない
| Alice | Engineer |
このケースを 4 つのパーサに通しました (リポジトリの scripts/benchmarks/markdown-table-parsers/、2026-07-15 実測。GitHub Markdown API / marked 18.0.5 / remark-gfm 4.0.1 / remark-parse による厳格な CommonMark)。列数が食い違うと 4 つすべてでテーブルになりませんでした。
ハイフンの本数は話が別です。同じ実測で | - | - | も | -- | -- | も、GitHub Markdown API・marked・remark-gfm の 3 つでテーブルとして描画されました。ハイフン 3 つは読みやすさのための慣習であって要件ではありません。GitHub 自身のドキュメントは「3 つ以上」と書き、仕様は何も定めず、実装は 1 つを通します。つまりテーブルが描画されないとき、ハイフンを数えるのは出発点として誤りです。同じ論点は Markdown テーブルが崩れる原因 で詳しく扱っています。
区切り行が短いことが実際に効く例外は 1 つあります。外側のパイプを省いたうえでハイフン 1 つにすると、GitHub はそのブロックをリストとして解釈します。
h1 | h2
- | - ← ここは GitHub ではリストになる。`--- | ---` ならテーブルになる
a | b
エディタでは表示されるのに GitHub で表示されないテーブルは、まず区切り行の列数を、次に外側のパイプの有無を確認してください。
GitHub とエディタで空セルの扱いが違う
GFM では完全に空のセルが許容されています。
| 機能 | basic | pro |
| :--- | :---: | :---: |
| PDF 書き出し | | ✅ |
| API アクセス | | ✅ |
GitHub はこの空セルを正しく描画しますが、一部のエディタはパイプの連続を構文エラーと見なして行が崩れて見えることがあります。Markdown ソースは正しく、エディタのプレビューが間違っているケースです。最終的には GitHub 上でレンダリングして確認してください。
セル内のパイプ | をリテラルで使いたい
セル内のパイプは列の区切りとして解釈されてしまいます。バックスラッシュでエスケープするか、HTML エンティティ | を使います。
| 条件 | 意味 |
| --- | --- |
| `a \| b` | ビット OR |
| `a | b` | エンティティ表記 |
GitHub 上ではどちらも a | b として描画されます。バックスラッシュが GFM 標準ですが、Hugo や MkDocs などの非 GFM ツールチェーンで処理する README ではエンティティ表記のほうが安全です。
GitHub に貼ると正しく描画されるのに手元のエディタで崩れて見える場合は、たいていエディタ側の問題です。README テーブルの正解は常に github.com のプレビューで確認してください。
GFM テーブル固有の注意点
GitHub の Markdown レンダラーには、一般的な Markdown エディタと異なる挙動がいくつかあります。
セル内改行は <br> を使う
GFM のテーブル仕様ではセル内の改行を表現できません。次のように複数行で書いてもレンダリング時には 1 行に押し込まれます。
| 手順 | 説明 |
| --- | --- |
| 1 | 依存をインストール
してビルド |
セル内で改行したいときは <br> を使います。GitHub はこれをセル内の改行として描画します。
| 手順 | 説明 |
| --- | --- |
| 1 | 依存をインストール<br>してビルド |
| 2 | テスト実行<br>ロックファイルをコミット |
<br> は GitHub の Markdown サニタイザがテーブルセル内で残す、数少ない HTML タグの 1 つです（次節参照）。多くのエディタでも同様に描画されますが、もし違って見える場合は GitHub Gist に貼って実際の描画を確認してください。
セル内の書式: 強調・コード・リンク・バッジ
セルの中ではインライン Markdown が効きます。README のテーブルがステータス表や比較表として使えるのはこのためです。強調、インラインコード、リンク、画像、絵文字はいずれも描画されます。
| Package | Status | Docs |
| --- | --- | --- |
| `core` |  | [Read](./docs/core.md) |
| `cli` | :warning: experimental | [Read](./docs/cli.md) |
効かないものが 2 つあります。1 つはブロック要素で、見出し・リスト・コードフェンスはセル内に入れられません。セル先頭の # はそのまま文字の # として残ります。もう 1 つはパイプで、shields.io の URL や画像リンクに | が含まれるとそこでセルが割れます。?label=a|b のようなクエリ文字列は \| でエスケープするか %7C にパーセントエンコードしてください。上の「セル内のパイプ | をリテラルで使いたい」と同じ規則ですが、パイプが文章ではなく URL の中に埋もれていると見落としやすい箇所です。
CSV や JSON からテーブルを生成している場合は、バッジの Markdown を元データのセルに入れたままにしておきます。CSV to Markdown はその記述をそのまま通すので、再生成してもバッジ列が残ります。
HTML の混在制限
GitHub はセル内の HTML をセキュリティ上の理由で大幅に制限しています。<br> は改行として使えますが、<span style="...">、<font color> のようなインラインスタイルは無視されます。セル内で色やフォントサイズの変更はできません。<details> のようなブロックレベルのタグはテーブルの外では使えますが、セル内では効きません。
列の配置指定
区切り線に : を付ける配置指定は GitHub 上で正しく動作します。数値列を右寄せにするとバージョン番号や価格の一覧が読みやすくなります。
| プラン | 月額 |
| :--- | ---: |
| Free | $0 |
| Pro | $10 |
長いテーブルの折り返し
列数が多いテーブルは GitHub 上で水平スクロールが発生します。README を PC とモバイルの両方で読む想定なら、列数を 5〜6 列以内に抑えるか、テーブルを分割するのが実用的です。
よくある質問
README のテーブルをスプレッドシートで管理できますか？
はい。スプレッドシートで内容を管理し、更新のたびに CSV をエクスポートして CSV to Markdown で変換すれば、常に最新のテーブルを README に反映できます。
テーブルのセルにリンクを入れられますか？
入れられます。セル内に [テキスト](URL) の形式で Markdown リンクを記述すれば、GitHub 上でクリック可能なリンクになります。
テーブルのセル内で改行するには？
セル内で HTML の <br> タグを使います。書き方と制限は上の「セル内改行は <br> を使う」の節を参照してください。
まとめ
README に表を入れると情報の視認性が大きく上がります。手書きでパイプを並べるのは数行ならまだしも、行数が増えると現実的ではありません。CSV to Markdown を使えば CSV を貼り付けて実行するだけでテーブルが生成されるので、README を更新するたびに手作業で整形する必要がなくなります。