MarkdownはGitHubのREADME、プルリクエストの説明、ドキュメントサイト、メモアプリで広く使われています。GitHub Flavored Markdown（GFM）はCommonMark仕様をテーブル・タスクリスト・取り消し線・自動リンクで拡張しています。このチートシートですべてを一箇所にまとめます。

Markdownをリアルタイムでプレビュー →

見出し

# H1 — ページタイトル
## H2 — セクション
### H3 — サブセクション
#### H4
##### H5
###### H6

見出し階層でドキュメントを構造化します。H1は通常ドキュメントタイトル、H2/H3はセクションに使います。

強調

構文結果
*italic* または _italic_italic
**bold** または __bold__bold
***bold italic***bold italic
~~strikethrough~~strikethrough（GFMのみ）

リスト

順序なしリスト

- 項目1
- 項目2
  - ネストした項目（2スペースインデント）
  - 別のネスト項目
- 項目3

リストマーカーとして -、*、+ が使えます。リスト内で一貫性を保ちましょう。

順序付きリスト

1. 最初のステップ
2. 2番目のステップ
   1. サブステップ
   2. サブステップ
3. 3番目のステップ

実際の番号は重要ではありません。Markdownはどんな番号でも順番にレンダリングします。

タスクリスト（GFM）

- [x] リポジトリをセットアップ
- [x] READMEを書く
- [ ] CI設定を追加
- [ ] 最初のリリースを公開

GitHubのissueやPR、プロジェクトドキュメントでインタラクティブなチェックボックスとしてレンダリングされます。

コード

インラインコード

インラインコードにはバッククォートを使います：`variable_name`、`npm install`、`const x = 1`

フェンスコードブロック

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

サポートされている言語識別子：js、javascript、ts、typescript、python、py、bash、sh、go、rust、java、c、cpp、json、yaml、html、css、sql、diff、markdownなど多数。

シンタックスハイライトなしのコード

```
プレーンテキストブロック
シンタックスハイライトなし
```

リンク

[リンクテキスト](https://example.com)
[タイトル付きリンク](https://example.com "ホバータイトル")
[参照スタイルリンク][ref-id]

[ref-id]: https://example.com

自動リンク（GFM）

GFMはURLとメールアドレスを自動的にリンクに変換します：

https://github.com はクリック可能なリンクになる
user@example.com はmailtoリンクになる

画像

![代替テキスト](image.png)
![代替テキスト](image.png "オプションタイトル")
![参照スタイル][img-ref]

[img-ref]: /path/to/image.png

画像にリンクを付ける場合：

[![代替テキスト](image.png)](https://example.com)

テーブル（GFM）

| カラム1 | カラム2 | カラム3 |
|---------|---------|---------|
| セル    | セル    | セル    |
| セル    | セル    | セル    |

カラムの配置

| 左     | 中央   | 右     |
|:-------|:------:|-------:|
| 左寄せ | 中央   | 右寄せ |
  • :--- — 左寄せ（デフォルト）
  • :---: — 中央寄せ
  • ---: — 右寄せ

テーブルを完璧に揃える必要はありません — パイプが存在すれば十分です。

引用

> これはブロック引用です。
>
> 複数の段落にまたがることができます。

> ネストした引用レベル1
>> ネストした引用レベル2

水平線

これらはいずれも水平線を生成します：

---
***
___

脚注（GFM拡張）

この主張は引用が必要です。[^1]

[^1]: 出典：信頼できる参考文献、2024年。

MarkdownでのHTML

生のHTMLはほとんどのMarkdownレンダラーでサポートされています：

<details>
<summary>クリックして展開</summary>

ここに隠れたコンテンツ。GitHubでは**Markdown**がHTMLブロック内でも機能します。

</details>

GitHub READMEの折りたたみセクションによく使われます。

文字のエスケープ

バックスラッシュを使ってMarkdown文字をエスケープします：

\*イタリックにならない\*
\`コードにならない\`
\# 見出しにならない

エスケープ可能な文字：\、`、*、_、{、}、[、]、(、)、#、+、-、.、!

GitHub固有の拡張

メンション

@username — ユーザーをメンション
@org/team — チームをメンション

issue・PR参照

#123          — issue/PR番号123へのリンク
user/repo#123 — リポジトリをまたいだ参照
SHA           — 特定のコミットへのリンク（7文字以上）

絵文字（GFM）

:rocket: :white_check_mark: :warning: :tada:

GitHubは絵文字ショートコードリストからこれらをレンダリングします。よく使われるもの：

  • :warning: — ⚠️
  • :white_check_mark: — ✅
  • :x: — ❌
  • :rocket: — 🚀
  • :memo: — 📝

CommonMark vs GFM

機能CommonMarkGFM
段落・見出し・リスト✅✅
フェンスコードブロック✅✅
強制改行✅✅
テーブル❌✅
タスクリスト❌✅
取り消し線❌✅
自動リンク部分的✅
メンション/issue参照❌✅

GitHub向けに書く場合はGFMを自由に使えます。最大限の移植性（静的サイトジェネレーター、他のツール）には CommonMark に留めましょう。

READMEのベストプラクティス

優れたGitHub READMEは通常これらを含みます：

  1. プロジェクトタイトルと1行の説明
  2. バッジ — ビルドステータス、バージョン、ライセンス
  3. インストール — コマンドのコードブロック
  4. 使用方法 — コードを含む短い例
  5. APIリファレンス — 主要なオプションのテーブルまたはリスト
  6. コントリビューティング — CONTRIBUTING.mdへのリンク
  7. ライセンス — ライセンスタイプの1行

Markdownをプレビューする

ライブプレビューなしでMarkdownを書くとエラーが起きやすい — 特にテーブルとネストしたリスト。コミットする前にプレビューツールにコンテンツを貼り付けてレンダリングを確認しましょう。

ライブMarkdownプレビューを試す → — GitHub Flavored Markdownをリアルタイムでレンダリング、アカウント不要。