GitHub READMEで見やすい表を作る完全ガイド（配置・幅・絵文字）

GitHubのREADMEには表（テーブル）を載せることがよくあります。機能比較表・対応OS表・コマンドオプション一覧・パラメータ表・対応バージョン表など、用途は多彩。本記事ではGFM Tables Extension に沿った「読まれるREADME表」の作り方を、配置・幅・絵文字・改行・トラブル対処まで丁寧に解説します。

最小構成：3行で表が出来る

GFMの表の最小構成は3行。1行目がヘッダ、2行目が区切り行、3行目以降がデータ行です。

| 名前 | 役割 | | --- | --- | | Alice | フロント | | Bob | バックエンド |

パイプ「|」で列を区切り、区切り行のハイフン「---」が3つ以上あればOK。1個でも動きますが、慣習として3つ書くことが多いです。本ツール（CSV→Markdown表変換）の出力もこの形式で揃えています。

配置：左寄せ・中央寄せ・右寄せ

区切り行のコロン（:）の位置で列ごとの配置を指定できます。GFM Tables Extension の正式機能で、GitHub・GitLab・各種Markdownレンダラが対応しています。

・| :--- | → 左寄せ（既定）
・| :---: | → 中央寄せ
・| ---: | → 右寄せ

| 項目 | 単価 | 数量 | | :--- | ---: | :---: | | りんご | 150 | 3 | | ぶどう | 600 | 1 |

単価のような数字列は右寄せにすると、桁が揃って見やすくなります。「項目」列は左寄せ、「数量」のような短い数字は中央寄せが定番。本ツールはデフォルトで左寄せ出力なので、配置を変えたいときは出力後に手で「---」を「:---」「:---:」「---:」に書き換えてください。

列幅は基本的に制御できない（と心得る）

GFMの表には列幅指定の構文はありません。<table style="width:300px"> のような直接的なHTMLを書けば一応反映されますが、GitHubは README 上のHTMLを限定的にしか許容しないため、style属性の効きにくさや脆さがあります。

実用的な対処は次の3つ。

・列順を入れ替える：長文の列を一番右に寄せると、横スクロールせずに見える表になりがちです。
・長文セルは で改行する：本ツールはセル内改行を自動で に変換します。
・あえて2つの表に分割する：項目が多すぎる場合は、概要表＋詳細表に分けた方が読まれやすくなります。

絵文字でチェックマーク・状態を表現

READMEの表でよく見るのが、対応／非対応・実装状況の絵文字表現。GitHubは Markdown 内で絵文字ショートコード（:white_check_mark: など）と Unicode 絵文字の両方が使えます。

| 機能 | Web | iOS | Android | | :--- | :---: | :---: | :---: | | ログイン | ✅ | ✅ | ✅ | | プッシュ通知 | — | ✅ | ✅ | | ダークモード | ✅ | 🚧 | ❌ |

✅（U+2705）対応、❌（U+274C）非対応、🚧（U+1F6A7）工事中、— （U+2014）該当なし、が定番。CSVから貼り付ける場合、Excel側で記号列を別に作って混入させると、本ツールが自動でMarkdown表に組み込みます。

セル内の改行と長文： が定番

Markdown表のセル内では通常の改行（Enter）が効きません。1セル内に複数行のテキストを入れたい場合は  を直接書きます。GFMはセル内のインラインHTMLとして を許容しています。

| API | 説明 | | :--- | :--- | | GET /users | ユーザー一覧を返す<br>クエリ：?limit=20&offset=0 |

本ツールは、ExcelやスプレッドシートでAlt+Enter（Macは Ctrl+Option+Enter）でセル内改行した値を貼り付けると、自動で に置換して出力します。手で書く手間が省けるため、長めの説明セルを含むAPIリファレンス表などに便利です。

よく作るパターン3種：機能比較・対応OS・コマンド一覧

READMEで頻出する3つの定番パターン。Excelで下書き → 本ツールで変換 → README貼り付け、という流れで毎回作れます。

機能比較表（自社サービス vs 競合）

| 機能 | 自社 | 競合A | 競合B | | :--- | :---: | :---: | :---: | | 無料プラン | ✅ | ❌ | ✅ | | API公開 | ✅ | ✅ | ❌ | | 日本語サポート | ✅ | ❌ | ❌ |

対応OS表

| OS | バージョン | ステータス | | :--- | :--- | :---: | | Ubuntu | 22.04 / 24.04 | ✅ | | macOS | 14 / 15 | ✅ | | Windows | 11 (WSL2) | 🚧 |

コマンドオプション一覧

| オプション | 必須 | 説明 | | :--- | :---: | :--- | | --input | ✅ | 入力ファイルのパス | | --output | — | 出力先（省略時は標準出力） | | --verbose | — | 詳細ログを表示 |

いずれも本ツールでExcelの内容を一発変換できる範囲です。あとは README に貼って、GitHub上でプレビューして体裁を確認してください。

CSV→Markdown表変換ツール → /csv-to-markdown/

本記事は GitHub Flavored Markdown Specification の Tables (extension) 節、および GitHub Docs「Organizing information with tables」を参照しています。GFM は CommonMark Spec 0.31.2 を基盤として、表・取り消し線・タスクリスト・自動リンクの4つを拡張しています。