Markdown を書いていると、表やタスクリストが環境によって表示されたり、ただの文字列になったりする。CommonMark と GitHub Flavored Markdown（GFM）の違いは何となく知っていたが、どこまでが GFM の追加機能なのか曖昧だったので仕様を確認した。

GFM は CommonMark を土台に、主に次の機能を追加している。

• 表
• タスクリスト
• 取り消し線
• < と > で囲まない URL やメールアドレスの自動リンク
• 一部の raw HTML を表示しないためのフィルタリング

見出し、箇条書き、引用、リンク、画像、フェンスコードブロック、HTML コメントなどは CommonMark に含まれる。自分はフェンスコードブロックと HTML コメントも GFM の追加機能だと思っていたが、これは間違いだった。

CommonMark と GFM の関係

CommonMark は、Markdown の曖昧な部分を仕様とテスト例で定義している。

GFM はそこへ GitHub で使う拡張を加えたものだ。ただし、GitHub で見かける機能がすべて GFM の仕様というわけではない。GitHub の画面側の機能とは分けて考える必要がある。

主要機能の比較

○は仕様に含まれ、×は仕様に含まれないことを示す。実際に表示できるかどうかは、利用する Markdown パーサーと設定にも依存する。

GFM で追加される記法と表示例

表

見出し行の次にハイフンを使った区切り行を置く。コロンを付けると列の配置も指定できる。

| 項目       | 対応状況 |
| ---------- | :------: |
| CommonMark |    ×     |
| GFM        |    ○     |

表示例:

CommonMark だけを処理する環境では、上記は表ではなく通常の段落として扱われる。

タスクリスト

通常のリスト項目を [ ] または [x] で始める。xを付けた項目は完了状態になる。

- [x] 仕様を確認する
- [ ] 表示結果を確認する

表示例:

• 仕様を確認する
• 表示結果を確認する

GFM 仕様が定めているのはチェック状態の表示である。チェックボックスを画面上で操作して文書を書き換えられるかどうかは、GitHub など各サービスの実装に依存する。

取り消し線

文字列を 2 個のチルダで囲む。

~~古い手順~~ 新しい手順

表示例:

古い手順 新しい手順

GFM 仕様では 1 個または 2 個のチルダを扱うが、実装によっては 2 個だけに対応する。互換性を考えると~~を使うのが無難である。

URL とメールアドレスの自動リンク

CommonMark にも自動リンクはあるが、URL またはメールアドレスを<と>で囲む必要がある。GFM では山括弧のない URL やメールアドレスも自動的にリンクへ変換される。

CommonMark でもリンクになる: <https://example.com/>
GFM ではこれもリンクになる: https://example.com/

上の 2 つは対応するパーサーではリンクとして表示される。ここでは例示用 URL への外部リンクを作らないよう、コードブロックで記法だけを示した。

「自動リンクは GFM だけの機能」と覚えると CommonMark の自動リンクと混同する。山括弧なしの URL までリンクになるのが GFM 拡張、と区別すると分かりやすい。

一部の raw HTML を無効化する

CommonMark は raw HTML を許可する。GFM にはtitle、textarea、style、xmp、iframe、noembed、noframes、script、plaintextタグをフィルタリングする拡張がある。

これは便利な表示記法を増やす機能ではなく、埋め込まれた HTML が Markdown 以降の表示へ影響するのを抑えるための違いである。

GFM 固有ではない記法

フェンスコードブロック

バックティックまたはチルダを 3 個以上並べるフェンスコードブロックは CommonMark の仕様に含まれる。開始フェンスの後ろには、言語名などを示す info string を指定できる。

```javascript
const message = "CommonMarkでも使える"
console.log(message)
```

言語名をどのように扱うかは CommonMark 仕様で強制されていないが、多くの実装ではシンタックスハイライトに利用される。コード例には可能な限り適切な言語名を指定したほうがよい。

HTML コメント

次の HTML コメントも GFM の追加機能ではなく、CommonMark で raw HTML として扱われる。

<!-- この内容はHTMLの表示結果には現れない -->

ただし、raw HTML を許可するか、サニタイズするかはパーサーやサービス側の設定にも左右される。

GFM を利用する方法

GFM の記法を使うには、GFM に対応したパーサーやプラグインが必要である。このブログでは MDX の処理にremark-gfmを組み込み、表、タスクリスト、取り消し線、自動リンクを利用できるようにしている。

CommonMark だけの環境で表を表現する場合は raw HTML のtable要素を使う方法もある。ただし、処理系が raw HTML を無効化している可能性があり、GFM の表と完全に同じ移植性が得られるわけではない。

調べて分かったこと

GFM を CommonMark とは別の Markdown だと思うと分かりづらい。CommonMark に表やタスクリストなどを足したもの、と考えると整理しやすかった。

特に紛らわしかったのは自動リンクで、山括弧付きは CommonMark、山括弧なしまでリンクになるのが GFM の拡張である。別の環境へ Markdown を移したときに表示が崩れたら、まず GFM が有効か確認することにする。

参考

https://spec.commonmark.org/current/

https://github.github.com/gfm/

GitHub - remarkjs/remark-gfm: remark plugin to support GFM (autolink literals, footnotes, strikethrough, tables, tasklists)

remark plugin to support GFM (autolink literals, footnotes, strikethrough, tables, tasklists) - remarkjs/remark-gfm

GitHub

おしまい