GitHubマークダウン完全ガイド — READMEやIssuesで使える書き方
READMEを書いていて表がうまく揃わなかったり、Issueに貼ったコードがただの文字列になってしまったり——GitHub上のMarkdownで一度は詰まったことがある人は多いはずです。GitHubはMarkdownの基本仕様に独自拡張を加えた「GitHub Flavored Markdown（GFM）」を採用しており、README・Issues・Pull Request・Wikiなど、ほぼすべての入力欄で共通して使えます。
この記事では、README作成やIssue・PRのやり取りで実際によく使う書き方を、GitHub公式ドキュメントを基に整理しました。
見出し
行頭に # を1〜6個つけると、その数に応じた階層の見出しになります。
# 見出し1
## 見出し2
### 見出し3READMEでは通常、タイトルに1つだけ # を使い、以降のセクションは ## から始めるのが一般的です。見出しを飛び級（# の次に直接###など）させると文書構造が分かりにくくなるため、上から順に階層を下げていきます。
文字装飾
| 装飾 | 記法 | 表示例 |
|---|---|---|
| 太字 | text または text | 太字 |
| 斜体 | text または text | 斜体 |
| 取り消し線 | ||
| 上付き文字 | <sup>text</sup> | HTMLタグで指定 |
| 下付き文字 | <sub>text</sub> | HTMLタグで指定 |
太字と斜体は記号を混同しやすいので注意します。**は太字、単独の*や_は斜体です。両方使いたいときは text のように3つ重ねます。
リスト
箇条書きは -、*、+ のいずれかを行頭に置きます。番号付きリストは 1. のように数字とピリオドです。
- 項目A
- 項目B
- 項目Bのネスト
- 項目C
1. 最初の手順
2. 次の手順
1. 手順のネスト
3. 最後の手順ネストはインデント（半角スペース2〜4個）で表現します。番号付きリストは実際にレンダリングされる際、記述した数字に関わらず自動で連番が振り直されるため、途中に項目を差し込んでも数字を書き直す必要はありません。
コードブロック
3つのバッククォート(```)で前後を挟み、開始側に言語名を書くとシンタックスハイライトが効きます。
例えば、コード内で言語名にjavascriptと書くと、キーワードや文字列に色がつき、開始側を空欄にすると装飾なしの単純なコードブロックになります。
インラインでコードの一部だけを示したいときは、1つのバッククォートで単語を挟みます（例: 変数名やコマンド名など短い記述向け）。
テーブル
パイプ(|)で列を区切り、1行目がヘッダー、2行目が区切り線、3行目以降がデータ行です。区切り線のコロン(:)の位置で揃え方を指定できます。
| 左揃え | 中央揃え | 右揃え |
|:-------|:-------:|-------:|
| A | B | C |
| 長い文字列 | 短 | 123 |- |:-------|（左にコロン）→ 左揃え
- |:-------:|（両側にコロン）→ 中央揃え
- |-------:|（右にコロン）→ 右揃え
- コロンなしはデフォルト（左揃え）
列の幅は自動調整されるため、ソース上でパイプの位置を厳密に揃える必要はありません。
チェックリスト
- と - [x] でチェックボックス付きのリストになります。
- [x] 設計レビュー完了
- [ ] 実装
- [ ] テスト作成IssueやPRの説明欄に書くと、実際にクリックして完了/未完了を切り替えられるインタラクティブなチェックボックスとして表示されます。作業のTODOリストや、PRのマージ前チェック項目としてよく使われます。Issue本文にチェックリストがあると、そのIssueへのリンクを貼った箇所に進捗（完了数/全体数）が自動表示される機能もあります。
リンクと画像
[表示テキスト](URL)
画像は先頭に ! がつくだけでリンクと同じ構文です。相対パスでリポジトリ内の画像を指定することもできます。
折りたたみセクション
長いログやオプションの補足情報は <details>と<summary>タグで折りたたんで表示できます。
<details>
<summary>クリックして詳細を表示</summary>
ここに折りたたまれる内容を書きます。
Markdownの記法もそのまま使えます。
</details>summaryタグの直後に空行を1つ入れないと、中身がMarkdownとして解釈されずそのまま表示されてしまうので注意します。デフォルトで開いた状態にしたい場合は <details open>のようにopen属性を追加します。
GitHub独自の拡張機能（GFM）
READMEやIssuesだけで使える、GitHub独自の記法もあります。
- @メンション: @ユーザー名 と書くと、そのユーザーに通知が飛びます（Issue・PRのコメント内で有効）。
- Issue/PR参照: #123 のように書くと、同じリポジトリ内のIssueやPR番号への自動リンクになります。別リポジトリを参照する場合は オーナー名/リポジトリ名#123 のように書きます。
これらはREADME.mdのようなファイル内では動作せず、Issues・PR・コミットメッセージなど「アクティビティ」に関連する場所でのみ機能します。
Mermaidダイアグラム
コードブロックの言語名をmermaidにすると、簡単な図表記法からフローチャートやシーケンス図をその場で描画できます。追加のツールやレンダリング環境は不要です。
graph TD
A[リクエスト受信] --> B{認証OK?}
B -->|Yes| C[処理を実行]
B -->|No| D[401を返す]graph TD は上から下（Top-Down）方向のフローチャートを意味します。矢印の間に |ラベル| を挟むと、分岐の条件を表示できます。シーケンス図や円グラフなど、他の図の種類もMermaid記法自体でサポートされています。
まとめ
GitHubのMarkdownは基本文法さえ押さえれば、あとはテーブル・チェックリスト・折りたたみ・Mermaidといった拡張機能を必要な場面で組み合わせるだけです。READMEは見出しとテーブルで構造化し、IssueやPRはチェックリストと@メンション・#参照で進捗と関係者を明確にする——用途に応じて使い分けると、ドキュメントもやり取りもぐっと読みやすくなります。
本記事の記法は GitHub公式ドキュメント（Basic writing and formatting syntax / Organizing information with collapsed sections / Creating diagrams）を基に確認しています。
