マークダウン 拡張記法ガイド:markdown テーブル(表)・脚注・タスクリストの書き方

マークダウンの拡張記法とは、John Gruber が2004年に公開したオリジナル仕様のあとから追加された書式要素の総称です。 2004年の仕様が定義したのは11種類の基本要素だけで、表(テーブル)、脚注、タスクリスト、打ち消し線は一切含まれていませんでした。その空白は後続のプロジェクトが埋めていきます。MultiMarkdown が2005年に表と脚注を導入し、2006年に登場した Pandoc はあらゆるプロセッサの中で最大の拡張セットを備え、CommonMark が2014年に拡張の余地を残しつつコア仕様を標準化し、GitHub は2017年に GFM 仕様を公開しました。このページのすべての要素はエディタのライブプレビューでそのまま描画されるため、5秒ほど貼り付けるだけで、目的のアプリが対応しているかどうかを確認できます。

対応状況マトリクス

全12種類の拡張要素すべてに対応しているアプリケーションは存在しないため、公開前に必ず出力先の対応状況を確認してください。 代表的な4つの出力先でも、対応状況は大きく異なります。

実用的な目安として、表、フェンス付きコードブロック、打ち消し線、タスクリストはほぼどこでも描画されます。逆に、定義リスト、ハイライト、下付き文字、上付き文字の4要素は最も失敗しやすい要素です。

表(テーブル)

markdown の表はパイプ文字(|)で列を区切り、3本以上のハイフンによる区切り行でヘッダー行を示します。 外側のパイプはほとんどのパーサーで省略できますが、互換性が高まるため付けたままにしておくのがおすすめです。

| Feature | Status |
| :------ | -----: |
| Export  | Done   |
| Sync    | Open   |

区切り行のコロンで文字揃えを制御します。:--- は左揃え、:---: は中央揃え、---: は右揃えです。パーサーはその列のすべてのセルに揃えを適用します。ハイフンの本数は列ごとに揃える必要はありません。セル内にパイプ文字そのものを表示したいときは HTML エンティティ | を書きます。GitHub ではバックスラッシュによるエスケープ \| も使えます。セルには太字やコードスパンなどのインライン書式は使えますが、リストや見出しなどのブロック要素は入れられません。

この記法は MultiMarkdown が2005年に導入し、GFM が2017年に採用しました。GitHub、GitLab、Obsidian、Pandoc は表を描画します。Discord は描画しません。

フェンス付きコードブロック

フェンス付きコードブロックは3つのバッククォートで開始・終了し、2004年仕様の4スペースインデント方式と違ってインデントが不要です。 ほとんどのパーサーでは、3つのチルダも代替フェンスとして使えます。

```python
def total(items):
    return sum(items)
```

開始フェンスの直後に言語識別子を置くと、シンタックスハイライトが有効になります。多くの Web レンダラーの内部で使われているライブラリ highlight.js は約200言語の定義を備えており、よく使われる識別子には python、js、json、bash、sql があります。コードブロックの中に別のコードブロックを表示したいときは、外側のフェンスをバッククォート4つにします。

対応範囲は拡張要素の中で最も広く、GitHub、Obsidian、Discord、Pandoc のすべてがフェンス付きブロックを描画し、4つとも言語ハイライトを適用します。

脚注

markdown の脚注は2つの部分で構成されます。本文中に [^1] と書く参照マーカーと、ファイル内の任意の場所に [^1]: に続けて書く定義です。 レンダラーはすべての定義をページ下部に集め、参照と定義を双方向のリンクでつなぎます。

The claim has a published source.[^1]

[^1]: Smith, 2024, p. 41.

識別子には数字だけでなく単語も使えます。出力の番号はラベルではなく文書内の登場順で振られるため、[^note] は [^1] とまったく同じように動作します。定義の下に4スペースのインデントで段落を続ければ、1つの脚注に複数の段落を含められます。

脚注は MultiMarkdown が2005年に実装し、Pandoc と Obsidian は完全対応、GitHub は2021年に脚注の描画を追加しました。Discord は脚注に対応していません。

見出しID

カスタム見出しIDは見出し行の末尾に波かっこで記述します。## Refund Policy {#refunds} と書くと、id="refunds" を持つ h2 要素が出力されます。 このIDはリンクや CSS から参照できる安定したアンカーになります。

## Refund Policy {#refunds}

Jump straight to [the refund policy](#refunds).

リンクは、ハッシュ(#)とIDをリンク先に指定した通常の markdown リンクです。ページの完全な URL に #refunds を付ければ、外部ページからも同じ位置に到達できます。

波かっこ形式を解釈するのは Pandoc と PHP Markdown Extra です。GitHub はこの形式を無視しますが、見出しテキストから自動的にIDを生成するため、#refund-policy へのリンクは GitHub でも機能します。Obsidian は見出しリンクに独自の [[Note#Heading]] 形式を使います。Discord はメッセージ内の見出しは描画しますが、アンカーの仕組みがありません。

定義リスト

定義リストは、1つの用語と1つ以上の定義を組み合わせる記法です。用語を1行に単独で書き、次の行からコロンとスペースで始まる定義を続けます。

Markdown
: A plain-text formatting syntax released in 2004.

Parser
: Software that converts markdown into HTML.
: Also called a processor.

出力は <dt> と <dd> を子に持つ本物の <dl> 要素になるため、用語集の作成やスクリーンリーダーでの読み上げに効果があります。コロン行を重ねれば、1つの用語に複数の定義を付けられます。

対応範囲は狭い要素です。この記法を定義したのは PHP Markdown Extra で、Pandoc と MultiMarkdown も解釈します。GitHub と Obsidian はコロン行をただのテキストとして表示し、Discord も同様です。GitHub では生の <dl> HTML が確実な代替手段になります。

打ち消し線

打ち消し線はテキストの両側を2つのチルダで囲む記法で、like this のように取り消し線付きで描画されます。 GFM 由来の要素で、HTML 出力は <del> 要素です。

~~Ship v2 on Friday.~~ Moved to Monday.

GitHub は片側1つのチルダも受け付けます。それでも移植性のためにチルダ2つを使ってください。Pandoc では1つのチルダは下付き文字を意味するため、たった1文字の差で意味が反転してしまいます。

対応状況はほぼユニバーサルで、GitHub、Obsidian、Discord、Pandoc のすべてがチルダ2つの打ち消し線を描画します。

タスクリスト

markdown のタスクリスト項目は通常のリスト項目と同じ書き出しに角かっこを追加します。- [ ] が未完了タスク、- [x] が完了タスクです。 空の角かっこの中のスペースは必須です。

- [x] Draft the outline
- [x] Write the copy
- [ ] Publish the page

この記法は GitHub が2013年に導入し、Issue やプルリクエストではチェックボックスがインタラクティブになり、クリックすると元の markdown が更新されます。GitHub はタスクの集計も行い、Issue には「2 of 3 tasks」のような進捗が表示されます。Obsidian は閲覧ビューでクリック可能なチェックボックスを描画し、Pandoc はタスクリストを HTML のチェックボックスに変換します。Discord は角かっこを入力した文字のまま表示します。

絵文字

markdown ファイルに絵文字を入れる方法は2つあります。Unicode 文字を直接貼り付けるか、ショートコード展開に対応したアプリケーションで :rocket: のようなショートコードを入力するかです。 貼り付けた絵文字は UTF-8 ファイルであれば必ず残るため、ショートコードが使えない環境でも 🎯 は表示されます。

Release day :tada: went live at 9 am.

ショートコードは絵文字の名前を2つのコロンで挟んだものです。GitHub は約1,800個のショートコードを展開し、Discord は独自のセットに加えてサーバーのカスタム絵文字を展開します。Obsidian はショートコードにコミュニティプラグインが必要ですが、貼り付けた絵文字はそのまま表示します。Pandoc は emoji 拡張を有効にした場合のみショートコードを展開します。名前はプラットフォームごとに異なるため、GitHub で使えるショートコードが他の場所でも使える保証はありません。

ハイライト

ハイライトはテキストの両側を2つのイコール記号で囲む記法で、==like this== がマーカーを引いたような背景(通常は黄色)で描画されます。 HTML 出力は <mark> 要素です。

The deadline moved to ==14 March== at noon.

これは拡張要素の中でも特に移植性が低い記法です。Obsidian は標準で描画し、Pandoc は mark 拡張を有効にすると解釈します(2023年リリースの Pandoc 3.0 から利用可能)。GitHub と Discord はイコール記号をそのまま表示します。記法が使えない環境でも、HTML をそのまま通すレンダラーであれば <mark> タグが機能し、これには GitHub の readme ファイルも含まれます。

下付き文字と上付き文字

下付き文字は H2O のように文字を1つのチルダで囲み、上付き文字は x^2^ のように1つのキャレットで囲みます。 どちらの形式も一般的な Web フレーバーではなく、Pandoc の拡張セットに由来します。

H~2~O freezes at 0 degrees.
E = mc^2^ dates from 1905.

Pandoc はこれらを <sub> と <sup> 要素に変換します。GitHub と Obsidian はチルダ形式とキャレット形式を無視しますが、HTML タグはそのまま通すため、H₂O はどちらでも機能します。Discord はどちらにも対応していません。チルダの衝突には注意してください。1つのチルダで打ち消し線になるアプリでは、下付き文字にするつもりのテキストが取り消し線になってしまいます。

URLの自動リンク

URLの自動リンクは、https://example.com のような裸のアドレスを、かっこ記法なしでクリック可能なリンクに変換する機能です。 GFM が2017年の仕様で autolink 拡張としてこの挙動を正式化しました。

Full docs at https://example.com/docs

GitHub と Discord は裸の URL をリンク化し、Obsidian も閲覧ビューで同様に動作します。Pandoc では autolink_bare_uris 拡張を有効にしない限りこの挙動はオフのままです。URL をリンクにしたくないときはバッククォートで囲んでください。コードスパンは決してリンク化されないため、設定サンプルやプレースホルダーのドメインでは https://example.com がプレーンテキストのまま残ります。

よくある質問

拡張記法は公式の markdown 仕様に含まれますか?

いいえ。2004年の仕様が定義するのは11種類の基本要素で、このページの要素はすべて後発のフレーバーやプロセッサに由来します。 markdown には統括団体が存在せず、それがアプリケーションごとに対応状況が異なる理由です。

拡張記法に最も多く対応している markdown フレーバーはどれですか?

最も対応範囲が広いのは Pandoc で、30種類を超えるオプションの記法拡張を備え、このページの全12要素を解釈します。 ただし Web 公開の実用的なターゲットは GFM です。GitHub、GitLab、そして最近のエディタの多くが GFM に準拠しているためです。

表が GitHub では描画されるのに Discord では描画されないのはなぜですか?

Discord はチャット向けに絞り込んだ狭い markdown サブセットを実装しており、表、脚注、タスクリスト、定義リストを省いています。 このサブセットに含まれるのは太字、斜体、打ち消し線、見出し、フェンス付きコードブロックです。Discord に投稿するコンテンツは、この5要素の範囲内に収めてください。

公開前に拡張記法をテストするにはどうすればよいですか?

オンラインエディタのライブプレビューに要素を貼り付けてください。GFM と脚注を1秒以内に描画します。 それ以外の出力先については、2行程度のサンプルを対象アプリ本体に貼り付けて確認してください。代表的な4つのケースは対応状況マトリクスでカバーしています。