GitHub Flavored Markdownとは
GitHub Flavored Markdown (GFM) はCommonMarkを基礎に、表、タスクリスト、取り消し線、自動リンクなどを拡張した形式です。拡張構文に対応していても、GitHubのサービス全体と同じ動作になるとは限りません。
公開先が対応する構文を確認し、以下の例をMarkdownビューアと公開先の両方で試してください。
この記事は文書でよく使う構文を扱います。完全な仕様ではありません。厳密な解析規則はGFM公式仕様を参照してください。
表
表は、最初に頼りになるGFM機能です。パイプとハイフンで作ったグリッドが、本物のHTMLテーブルとしてレンダリングされます。
| 機能 | 素のMD | GFM |
| --- | :--- | :---: |
| 表 | ❌ | ✅ |
| タスクリスト | ❌ | ✅ |
| 取り消し線 | ❌ | ✅ |
区切り行のコロンが配置を制御します。:--- 左寄せ、---: 右寄せ、:---: 中央揃えです。表はきれいなグリッドに保ちましょう。GFMは結合セルやネストセルに対応していません。
空行は表の境界を読みやすくします。表示に失敗したら、まず見出し行と区切り行の列数、レンダラーの表への対応を確認します。
タスクリスト
タスクリストは箇条書きをチェックボックスに変えます。READMEやIssueで進捗を追うのに最適です。
- [x] プロジェクトをセットアップ
- [x] ドキュメントを書く
- [ ] リリースを出す
- [ ] フィードバックを集める
チェック済み項目は塗り潰されたチェックボックスに、未チェックは空になります。箇条書き・番号付きどちらでも機能しますが、箇条書きが最も読みやすいです。
取り消し線
取り消し線は単純ですが、編集を示したり古い内容をマークしたりするのに便利です。
この機能は ~~非推奨~~ 置き換え中です。
二重チルダ (~~このように~~) で囲むと、打ち消し線が引かれます。
自動リンクとコード
GFMはURLやメールアドレスの自動リンク化を行います。山括弧やMarkdownのリンク構文は不要です。
https://example.com を見るか、[email protected] 宛てにメールしてください。
コードスパンとコードブロック内では、Markdownの解析が無効になるため、エスケープせずに生の構文を表示できます。
ソースには演算子 `||` が文字として含まれています。
言語タグはコードの言語を示します。色付き表示にはレンダラー側の対応が必要です。フェンス自体を例示するときは、外側のフェンスを内側より長くします。
見出しと文書のアウトライン
見出しは、GFMの基礎であるCommonMarkにも含まれます。論理的な階層は節の移動を助けますが、見出しだけで文書全体のアクセシビリティが保証されるわけではありません。
# 文書タイトル (H1)
## セクション (H2)
### サブセクション (H3)
アウトラインをきれいに保つ習慣は2つ。文書のタイトルとしてH1を1つだけ使い、レベルを飛ばさないこと(H2からH4へ飛ぶと、スクリーンリーダーや目次ツールが頼る階層が壊れます)。
リストとネスト
GFMは番号付き・箇条書きリストを扱い、インデントでネストします。
1. 最初のステップ
2. 次のステップ
- サブ項目
- 別のサブ項目
3. 3番目のステップ
ネストは浅く(通常2階層まで)保ち、リスト項目を前後の段落から空行で区切って、段落に溶け込まないようにしましょう。
引用
引用は注記・警告・引用文を際立たせます。
> これは引用です。
> 複数行にまたげます。
視覚的にインデントされ、太字で叫ぶことなくコールアウトを際立たせるきれいな方法です。
文書で必要な機能を確認する
すべてのMarkdownビューアがすべてのGFM機能に対応しているわけではありません。弱いレンダラーは表を生のパイプで表示したり、タスクリストのチェックボックスを無視したりします。ビューアや変換ツールを選ぶときは、以下すべてを扱えることを確認しましょう。
| 構文 | 対応していない場合 | 対応している場合 |
|---|---|---|
| 表 | | が見える |
本物の表 |
| タスクリスト | 単なる箇条書き | チェックボックス |
| 取り消し線 | ~~ が見える |
打ち消し線 |
| 自動リンク | 単なるテキスト | クリック可能なリンク |
| フェンスコード(CommonMarkにも含まれる) | フェンス記号がそのまま表示 | 独立したコードブロック |
Markdownビューアで必要な例を試してください。メインビューアでは生のHTMLを省略します。脚注と数式は追加機能であり、GitHubとの完全な一致を保証するものではありません。機能が表示されない場合は、不具合と決めつけず、対応する方言を確認します。
構文とサービス固有の動作を分ける
| 要素 | 確認する層 | MD Openerのメインビューア |
|---|---|---|
| 表・タスクリスト・取り消し線 | GFMの拡張構文 | 対応する構文を描画する |
| フェンスコード | CommonMarkの基本構文 | コードを表示するが、言語名だけで色分けは保証されない |
| 脚注・ドル記号の数式 | レンダラーの追加機能 | 対応する参照と数式を描画する |
<details> などの生HTML |
レンダラーのHTML方針 | 生HTMLのマークアップを省略する |
| Issue参照・メンション・相対画像 | ホストとリポジトリの文脈 | GitHubのリポジトリ機能は再現しない |
表の区切りがない場合はソースを、隣の画像がない場合は素材を調べます。mermaid というコード言語名を書くだけでは、図が描画されることは保証されません。
変換に強いGFMを書く
同じソースからHTML、PDF、Wordを作れますが、形式によって表現は異なります。出力ファイルを別に確認してください。
- 表は MarkdownからHTML や MarkdownからPDF でも表のまま
- タスクリストは MarkdownからWord でも描画される
- 長いコード行の切れや折り返しを確認する
チェックボックスが操作可能な部品になるとは限らず、PDFの見出しがしおりになるとも限りません。受け手が必要とする機能を確認します。
今すぐGFMを試す
小さなGFMの例を書き、ソースと表示結果を比較してみましょう。Markdownビューアを開き、このガイドのスニペットを貼り付ければ、表・タスクリスト・取り消し線が生き生きと描画されるのを確認できます。Markdownはブラウザ内で処理されます。ただし、外部画像URLへのアクセスは発生し得ます。