GitHub Flavored Markdownとは
素のMarkdownは、元の仕様のままだと意外と限定的です。見出し・リスト・コードブロック・リンクはありますが、表もタスクリストも取り消し線もありません。実務の文章にはもっと必要です。GitHub Flavored Markdown (GFM) はその隙間を埋めた拡張セットで、現代のWebにおける事実上の標準Markdownになりました。README、ドキュメントサイト、Issueトラッカー、チャットツール、そして大半のMarkdownビューアがGFMを前提としています。
今日Markdownを書くなら、ほぼ確実にGFMを書いています。その拡張を理解し、使うビューアが対応していることを確認するのが、綺麗にレンダリングされる文書と、中途半端にしか表示されない文書の分かれ目です。以下のスニペットはどれも、GFMに完全対応した Markdownビューア で試せます。
このガイドでは、GFMのすべての拡張機能を、コピペ例と注意点付きで扱います。
表
表は、最初に頼りになるGFM機能です。パイプとハイフンで作ったグリッドが、本物のHTMLテーブルとしてレンダリングされます。
| 機能 | 素のMD | GFM |
| --- | :--- | :---: |
| 表 | ❌ | ✅ |
| タスクリスト | ❌ | ✅ |
| 取り消し線 | ❌ | ✅ |
区切り行のコロンが配置を制御します。:--- 左寄せ、---: 右寄せ、:---: 中央揃えです。表はきれいなグリッドに保ちましょう。GFMは結合セルやネストセルに対応していません。
表の前後には必ず空行を入れましょう。ないと表が前後の段落にくっつき、レンダリングに失敗することがあります。
タスクリスト
タスクリストは箇条書きをチェックボックスに変えます。READMEやIssueで進捗を追うのに最適です。
- [x] プロジェクトをセットアップ
- [x] ドキュメントを書く
- [ ] リリースを出す
- [ ] フィードバックを集める
チェック済み項目は塗り潰されたチェックボックスに、未チェックは空になります。箇条書き・番号付きどちらでも機能しますが、箇条書きが最も読みやすいです。
取り消し線
取り消し線は単純ですが、編集を示したり古い内容をマークしたりするのに便利です。
この機能は ~~非推奨~~ 置き換え中です。
二重チルダ (~~このように~) で囲むと、打ち消し線が引かれます。
自動リンクとコード
GFMはURLやメールアドレスの自動リンク化を行います。山括弧やMarkdownのリンク構文は不要です。
https://example.com を見るか、[email protected] 宛てにメールしてください。
コードスパンとコードブロック内では、Markdownの解析が無効になるため、エスケープせずに生の構文を表示できます。
結合には `+` ではなく `||` を使います。
フェンスコードブロックでは言語タグでシンタックスハイライトを付けられ、バッククォート（またはチルダ）を3つ以上重ねて入れ子にもできます。
見出しと文書のアウトライン
GFMの見出しは本物の文書アウトラインを作ります。順序通りに使えば、ナビゲートしやすくアクセシブルな文書になります。
# 文書タイトル (H1)
## セクション (H2)
### サブセクション (H3)
アウトラインをきれいに保つ習慣は2つ。文書のタイトルとしてH1を1つだけ使い、レベルを飛ばさないこと（H2からH4へ飛ぶと、スクリーンリーダーや目次ツールが頼る階層が壊れます）。
リストとネスト
GFMは番号付き・箇条書きリストを扱い、インデントでネストします。
1. 最初のステップ
2. 次のステップ
- サブ項目
- 別のサブ項目
3. 3番目のステップ
ネストは浅く（通常2階層まで）保ち、リスト項目を前後の段落から空行で区切って、段落に溶け込まないようにしましょう。
引用
引用は注記・警告・引用文を際立たせます。
> これは引用です。
> 複数行にまたげます。
視覚的にインデントされ、太字で叫ぶことなくコールアウトを際立たせるきれいな方法です。
「完全なGFM対応」が本当に意味するもの
すべてのMarkdownビューアがすべてのGFM機能に対応しているわけではありません。弱いレンダラーは表を生のパイプで表示したり、タスクリストのチェックボックスを無視したりします。ビューアや変換ツールを選ぶときは、以下すべてを扱えることを確認しましょう。
| GFM機能 | 弱いレンダラー | 完全GFMレンダラー |
|---|---|---|
| 表 | | が見える |
本物の表 |
| タスクリスト | 単なる箇条書き | チェックボックス |
| 取り消し線 | ~~ が見える |
打ち消し線 |
| 自動リンク | 単なるテキスト | クリック可能なリンク |
| フェンスコード | 単なるテキスト | 等幅ブロック |
GFMに完全対応した Markdownビューア はこれらすべてを正しく描画します。だからGFM対応は、確認すべき最も重要な機能です。
変換に強いGFMを書く
GFMは変換にも最適なソース形式です。同じ .md ファイルが、Web向けHTML、成果物PDF、レビュー用Wordのいずれにもなります。そしてGFM機能はどのエクスポートでも生き残ります。
- 表は MarkdownからHTML や MarkdownからPDF でも表のまま
- タスクリストは MarkdownからWord でも描画される
- コードブロックはどこでも書式が保たれる
GFMで一度書けば、あらゆる行き先に備えた内容になります。
今すぐGFMを試す
GFMを学ぶ最速の方法は、少し書いてレンダリングを見ることです。Markdownビューアを開き、このガイドのスニペットを貼り付ければ、表・タスクリスト・取り消し線が生き生きと描画されるのを確認できます。すべてGitHub Flavored Markdownに完全対応し、ブラウザ内でローカル処理されます。