【コピペで使える】GitHub Markdown（GFM）記法完全ガイド｜独自アラート[!NOTE]・タスクリスト・diff差分・Issue/PR連携まで徹底解説

GitHubでREADME.mdやIssue、Pull Request（PR）、Wiki、Discussionsを作成する際に、「GitHub独自のアラート枠（[!NOTE] や [!WARNING]）はどう書くの？」「差分がわかりやすいdiffコードブロックの書き方は？」「タスクリストやメンション、Issueの自動リンクを使いこなしたい」「Mermaid図や数式をGitHub上で綺麗に表示させたい」と思ったことはありませんか？

GitHubでは、標準のMarkdown仕様（CommonMark）を大幅に拡張した「GitHub Flavored Markdown（GFM）」が採用されています。GFMをマスターすると、プロジェクトの仕様書やREADMEの見栄えが劇的に向上し、チーム開発におけるプルリクエストのレビュー効率やIssueのコミュニケーションが圧倒的にスムーズになります。

本記事では、GitHub Markdown（GFM）の基本仕様から、公式アラート構文（全5種）、タスクリスト、diff差分ハイライト、メンション＆Issue自動クローズ構文、Mermaid図・数式対応、そのまま使えるREADME/PRコピペ用テンプレート、反映されない時のトラブル対処法までをわかりやすく完全網羅して解説します！

1. 【概要】GitHub Markdown（GFM）とは？標準Markdownとの違い

GitHub上で扱われるドキュメントは、標準的なMarkdown仕様を独自に拡張したGitHub Flavored Markdown（略称：GFM）というフォーマットに基づいています。

GFM（GitHub Flavored Markdown）の定義と特徴

オリジナルのMarkdown（John Gruber氏が2004年に策定）は、非常にシンプルなテキスト装飾機能しか備えていませんでした。その後、標準化仕様であるCommonMarkが策定されましたが、GitHubはソフトウェア開発の現場で必要とされる様々な実用的機能を追加し、公式仕様書（GFM Spec）として公開しています。

標準Markdown（CommonMark）とGFMの比較早見表

標準MarkdownとGFMでどのような違いがあるのかを一目で確認できる比較表がこちらです。

GitHub上でMarkdownが使える場所一覧

GitHubでは、リポジトリのトップページだけでなく、開発プロセスのあらゆる場所でMarkdownを使用できます。

• リポジトリトップ（README.md / CONTRIBUTING.md / SECURITY.md 等）: プロジェクトの説明やコントリビューションガイド。
• Issues（課題管理）: バグ報告や新機能の要望チケット、コメント欄。
• Pull Requests（プルリクエスト）: 変更内容の説明、レビューコメント、インラインコードコメント。
• Discussions（コミュニティ掲示板）: 質問、アイデア共有、Q&A。
• Wiki / Releases: プロジェクト専用Wikiページ、リリースノートの記述。
• GitHub Profile README: ユーザーや組織のプロフィールページの装飾。

2. 【最新仕様】GitHubアラート記法（[!NOTE] / [!WARNING] など全5種）

GitHubで最も人気があり視覚効果が高い拡張機能が「GitHubアラート（Alerts / Callouts）」です。引用構文（>）を拡張したもので、読者に特別な注意を促すボックスを専用アイコンとテーマカラー付きで表示できます。

GitHubアラートの基本構文と仕組み

書き方は極めて簡単です。引用記号 > の1行目に [!ALERT_TYPE] と記述し、2行目以降に本文を書きます。

> [!NOTE]
> ここにアラートの本文テキストを記述します。
> 複数行にわたる場合も行頭に `>` を付けます。

全5種類のアラート（NOTE / TIP / IMPORTANT / WARNING / CAUTION）一覧

GitHub公式でサポートされているアラートタイプは以下の全5種類です。それぞれの役割と実際の表示イメージを確認しましょう。

> [!NOTE]
> 有用な補足情報や背景コンテキストを読者に伝えます。

> [!TIP]
> 作業をより効率化するためのアドバイスやコツ、ベストプラクティスを提示します。

> [!IMPORTANT]
> 読者が目的を達成するために必須となる重要事項や手順を強調します。

> [!WARNING]
> 意図しない不具合や予期せぬリスクを回避するための警告事項です。

> [!CAUTION]
> データ消失やセキュリティリスク、破壊的変更を伴う危険な操作に対する最大級の注意喚起です。

アラート記法を書く際の注意点・ルール

• すべて大文字で書く: [!note] や [!Warning] のように小文字が混ざると認識されず、通常の引用としてレンダリングされます。必ず [!NOTE] のようにすべて大文字で記述してください。
• 1行目に他の文字を入れない: > [!NOTE] ここに本文 のように同じ行に本文を書くと無効になります。本文は必ず次の行（> 本文）から書き始めてください。
• 前後に空行を設ける: 通常の段落テキストとアラートボックスの間には、1行以上の空行を挟むことでレンダリングの不具合を防げます。

3. 【開発効率UP】タスクリスト（チェックボックス）の活用術

GitHubのタスクリスト（Task Lists）は、単にチェックボックスを描画するだけでなく、GitHubのシステムと強力に連携して進捗状況をリアルタイムに管理できる機能です。

タスクリストの書き方（未完了・完了）

箇条書き記号（- または *）の直後に [ ]（未完了）または [x]（完了）を記述します。

- [ ] 未完了のタスク（チェックなし）
- [x] 完了したタスク（チェックあり：小文字の x または大文字の X）
- [ ] [Issueタイトル](#123) リンクを含めることも可能

Issue/PRにおける進捗バー自動連動機能

IssueやPull Requestの本文（最初のコメント）にタスクリストを記述すると、以下のような自動連動機能が働きます。

• マウスクリックで状態更新: マークダウンのソースコードを編集しなくても、画面上でチェックボックスをクリックするだけで即座にチェックのON/OFFが切り替わります。
• ヘッダーに進捗カウンター表示: Issue一覧やPR画面の上部に「2 of 5 tasks（5個中2個完了）」のようなプログレスバーが自動表示されます。
• プロジェクトボードとの連携: GitHub Projects上でタスクの完了率がグラフ化されます。

階層化（ネスト）したサブタスクの作成法

複雑なタスクは、半角スペース2個または4個のインデントを付けることで階層化できます。

- [ ] フロントエンド開発
  - [x] ヘッダー・ナビゲーション実装
  - [ ] フォームバリデーション追加
  - [ ] レスポンシブ対応
- [ ] バックエンドAPI開発
  - [x] 認証エンドポイント作成
  - [ ] データベースマイグレーション実行

4. 【コード＆差分】シンタックスハイライト・diff表示・詳細折りたたみ

エンジニアの日常業務で最も頻繁に利用されるのが、コードブロックの高度な表示機能です。

言語別シンタックスハイライトの指定方法

バッククォート3個（```）の直後に言語識別子（言語名）を指定することで、キーワードや文字列に色がついたシンタックスハイライトが適用されます。

```typescript
interface User {
  id: number;
  name: string;
  isAdmin: boolean;
}

const getUser = (id: number): User => {
  return { id, name: "Alice", isAdmin: true };
};
```

主要な言語識別子には javascript (js), typescript (ts), python (py), go, rust (rs), json, yaml (yml), bash (sh), sql, html, css など数百種類が対応しています。

diff記法を使った「追加行（緑）」「削除行（赤）」の差分表示

コードの修正前・修正後を説明する際は、言語指定に diff を使用します。行頭に + を付けると緑色（追加）、- を付けると赤色（削除）でハイライトされます。

```diff
function calculateTotal(items) {
- const taxRate = 0.08; // 旧税率
+ const taxRate = 0.10; // 新税率（10%に更新）
  return items.reduce((sum, item) => sum + item.price, 0) * (1 + taxRate);
}
```

Pull Requestの概要欄や技術ブログで「どの行を変更したか」を直感的に伝えたい場合に絶大な効果を発揮します。

detailsタグとsummaryタグによるコードの折りたたみ表示

ログファイルや長いコードスニペット、巨大なJSONレスポンスをIssueやPRに貼る際は、HTMLの <details> と <summary> タグを使って折りたたむ（アコーディオン表示にする）のがGitHubにおけるマナーです。

<details>
<summary>🔍 エラーログの詳細を展開する（クリックで開閉）</summary>

```bash
Error: Connection timeout at Database.connect (db.ts:42)
    at async bootstrap (main.ts:15)
```

</details>

5. 【コミュニケーション】メンション・自動リンク・Issue自動クローズ

GitHub上でのチーム開発を円滑にするためのコミュニケーション機能も、Markdownのシンプルな記号で自動化されています。

ユーザー（@user）およびチーム（@org/team）メンション

@ユーザー名 を記述すると、該当ユーザーにGitHub通知が送信されます。また、GitHub Organizationに所属している場合は @組織名/チーム名 でチーム全体に一括メンションを飛ばすことも可能です。

@octocat レビューをお願いします！
@my-org/frontend-team フロントエンド班の皆さま、仕様変更のご確認をお願いします。

Issue・PR・コミットハッシュの短縮参照リンク

完全なURLを記述しなくても、以下の短縮構文で自動的にリンクに変換されます。

プルリクエストによるIssue自動クローズ（Fixes / Closes #123）

PRの説明文やコミットメッセージに特定のキーワードを添えてIssue番号を書くと、PRがデフォルトブランチ（main / master）にマージされた瞬間に、連動するIssueが自動的にクローズ（解決済みに）されます。

Fixes #42
Closes #108
Resolves #256

使用可能なキーワードには close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved があります。

絵文字ショートコード（:emoji:）の入力法

GitHubではコロンで囲んだショートコードを入力することで、絵文字を簡単に呼び出せます（例: :sparkles: → ✨、:rocket: → 🚀、:bug: → 🐛、:tada: → 🎉、:+1: → 👍）。エディタ上で : を入力するとオートコンプリート候補が表示されます。

6. 【高度な表現】GFM拡張記法（表・取り消し線・数式・Mermaid図）

GitHub Flavored Markdownの真骨頂は、ドキュメントの表現力を極限まで高める拡張機能にあります。

表（テーブル記法）の作成とテキスト配置（左・中央・右寄せ）

パイプ記号（|）とハイフン（-）で表を作成します。2行目の区切り行にコロン（:）を置く位置によって、テキストの配置（アライメント）を指定できます。

| 左寄せ（デフォルト） | 中央揃え | 右寄せ（数値用） |
| :--- | :---: | ---: |
| 項目A | 処理中 | ¥1,200 |
| 項目B | 完了 | ¥35,000 |

打ち消し線（~~取り消し~~）とURL自動リンク

• 打ち消し線: チルダ2個で囲む（~~古い仕様~~ → 古い仕様）。変更履歴や廃止された項目の明示に最適です。
• URL自動リンク: https://example.com や user@example.com のようにURLやメールアドレスを生テキストで書くだけで、<a> タグなしで自動的にクリック可能なハイパーリンクに変換されます。

LaTeX形式の数式表示（$ と $$）

GitHubでは、LaTeX（MathJax）形式による美しい数式レンダリングをネイティブサポートしています。

• インライン数式: ドル記号1つで囲む（例: $`E = mc^2`$ または $f(x) = ax + b$）
• ブロック数式（数式ブロック）: ドル記号2つ（$$）または ```math で囲む

$$
\sigma = \sqrt{\frac{1}{N} \sum_{i=1}^{N} (x_i - \mu)^2}
$$

Mermaid（マーメイド）によるフローチャート・シーケンス図埋め込み

GitHubでは、作図ツールを使わずにテキストだけでダイアグラムを生成できるMermaid.jsが標準統合されています。```mermaid で囲むだけで、リポジトリ上で美しいSVG図が自動描画されます。

```mermaid
graph TD
    A[ユーザーリクエスト] --> B{認証チェック}
    B -->|OK| C[APIサーバー処理]
    B -->|NG| D[401 Unauthorized]
    C --> E[(PostgreSQL DB)]
    E --> C
    C --> F[JSONレスポンス返却]
```

カラーチップ（HEXカラーコードの視覚化）

バッククォート内で `#0969da` のように6桁または3桁のHEXカラーコードを記述すると、GitHub上ではその色の小さなカラーチップ（色見本四角形）がコードの左横に自動プレビュー表示されます。デザインシステムやUIの仕様書で非常に便利です。

7. 【コピペで使える】実用テンプレート（README・PR・Issue）

ここまでに紹介したGFMの機能をフル活用した、実際の現場でそのまま使える実践テンプレートです。コピー＆ペーストしてプロジェクトに合わせてカスタマイズしてください。

高品質なプロジェクト用「README.md」テンプレート

# 🚀 プロジェクト名

[![CI/CD](https://github.com/owner/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/owner/repo/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

プロジェクトの一言概要（例: モダンなWebアプリケーション開発を加速するフルスタックフレームワーク）

## 🌟 主な特徴
- ⚡ **超高速パフォーマンス:** 最適化されたレンダリングエンジン
- 🔒 **堅牢なセキュリティ:** デフォルトでCSRF・XSS対策を完備
- 📦 **プラグイン拡張:** 豊富なエコシステム

> [!IMPORTANT]
> 本ライブラリの利用には **Node.js v20.0.0 以上** が必要です。

## 🛠️ クイックスタート

```bash
# リポジトリのクローン
git clone https://github.com/owner/repo.git
cd repo

# 依存関係のインストール
npm install

# 開発サーバーの起動
npm run dev
```

> [!TIP]
> `.env.example` を `.env` にコピーして環境変数を設定してください。

## 🗺️ アーキテクチャ構成

```mermaid
graph LR
    Client[Webクライアント] --> App[Node.js App]
    App --> DB[(PostgreSQL)]
    App --> Cache[(Redis)]
```

## 📝 コントリビューション
バグ報告や機能要望は [Issues](https://github.com/owner/repo/issues) よりお気軽にお寄せください。

レビューが劇的に加速する「Pull Request」テンプレート

## 📌 概要
- 変更の目的・背景を簡潔に記述

Fixes #123

## 🔄 変更内容
```diff
- 旧コード（削除部分）
+ 新コード（修正部分）
```

## ✅ レビュー前チェックリスト
- [ ] 単体テスト（Unit Test）がすべてパスしている
- [ ] TypeScriptの型チェックエラーがない
- [ ] ドキュメント・READMEを更新した

## 📸 動作確認・スクリーンショット
<details>
<summary>動作画面のキャプチャを展開する</summary>

![画面キャプチャ](画像URL)

</details>

> [!NOTE]
> 本PRマージ後、DBマイグレーションの実行が必要です。

バグ報告用「Issue」テンプレート

## 🐛 不具合の概要
発生している問題の簡潔な説明

## 🔁 再現手順
1. `npm start` を実行
2. ログイン画面で無効なパスワードを入力
3. エラーモーダルが表示されずフリーズする

## 💻 実行環境
| 項目 | バージョン / 情報 |
| :--- | :--- |
| OS | macOS Sonoma 14.5 |
| Node.js | v20.12.0 |
| ブラウザ | Google Chrome 125 |

> [!WARNING]
> ログ内にAPIキーや個人情報が含まれていないことを確認してから投稿してください。

8. 【トラブルシューティング】GitHubでMarkdownが崩れる原因と対処法

GitHubにMarkdownをプッシュした際によくある「表示崩れ」「意図通りにレンダリングされない」問題の解決チェックリストです。

9. まとめと関連記法チートシート

GitHub Flavored Markdown（GFM）は、現代のソフトウェア開発において最も標準的かつ表現力に優れたドキュメント作成ツールです。基本のMarkdown記法に加えてGFM独自機能を使いこなすことで、ドキュメントの読みやすさとチームの開発生産性を飛躍的に高めることができます。