GitHub の README や Issue を読んでいると、次のような記法を見かけることがあります。
> [!IMPORTANT]
> **以前のバージョンからアップグレードする場合**
>
> 設定方法が変更されています。
> アップグレード前に移行手順を確認してください。これは通常の Markdown の引用ではなく、GitHub がサポートしている Alerts という Markdown 拡張です。
GitHub 上では、IMPORTANT のような種類に応じてアイコンや装飾が付いた注意ボックスとして表示されます。
標準Markdownではない
まず押さえておきたいのは、次の部分です。
>これは標準的な Markdown の引用記法です。
一方、
[!IMPORTANT]を特別な意味として解釈する仕組みは、標準 Markdown の仕様ではありません。
つまり、
> [!IMPORTANT]
> 重要な情報ですという記法は、Markdown の引用構文を利用した GitHub独自の拡張記法です。
そのため、GitHub では注意ボックスとして表示されても、別の Markdown レンダラーでは単なる引用として表示される場合があります。
使用できるAlertの種類
GitHub では、主に次の5種類の Alert が利用できます。
NOTE
補足情報を示したい場合に使います。
> [!NOTE]
> この設定は省略可能です。TIP
便利な方法やおすすめの使い方を示す場合に使います。
> [!TIP]
> このコマンドを使うと設定を簡単に確認できます。IMPORTANT
ユーザーに必ず知っておいてほしい重要事項に使います。
> [!IMPORTANT]
> アップグレード前に設定ファイルをバックアップしてください。WARNING
問題が発生する可能性がある操作について注意を促す場合に使います。
> [!WARNING]
> この操作を行うと既存の設定が上書きされます。CAUTION
データ損失など、特に重大なリスクを伴う操作に使います。
> [!CAUTION]
> このコマンドを実行すると保存済みデータが削除されます。複数行を書く場合
Alert の中に複数行の文章を書く場合は、それぞれの行に > を付けます。
> [!IMPORTANT]
> 設定方法が変更されています。
>
> アップグレードする前に、
> 新しい設定方法を確認してください。空行を入れたい場合も、
>と書きます。
通常の Markdown の blockquote と同じ仕組みです。
太字やリンクも使える
Alert の中では、通常の Markdown 記法も利用できます。
> [!IMPORTANT]
> **アップグレードする前に確認してください**
>
> 詳細は[移行ガイド](docs/migration.md)を参照してください。README の中で重要なドキュメントへ誘導するときには便利です。
どんな場面で使うとよいか
Alerts は、README の文章を読みやすく整理するのに向いています。
たとえば、
- バージョンアップ時の注意事項
- 破壊的変更
- セキュリティ上の注意
- 設定時の補足
- よくあるミス
- 推奨設定
などです。
特に、
## Upgrade
アップグレード方法について説明します。
> [!IMPORTANT]
> バージョン2以降では設定ファイルの形式が変更されています。
次のコマンドを実行します。のように使うと、通常の本文と重要事項を明確に分けられます。
使いすぎには注意
便利な記法ですが、すべての情報を Alert にしてしまうと、かえって重要度が分かりにくくなります。
たとえば README が、
> [!NOTE]
> ...
> [!TIP]
> ...
> [!IMPORTANT]
> ...
> [!WARNING]
> ...のような注意ボックスだらけになると、どこを読むべきなのか判断しづらくなります。
基本的には通常の文章を使い、本当に目立たせたい情報だけを Alert にするのがよいでしょう。
GitHub以外では表示が変わる可能性がある
この記法を使う場合にもう一つ注意したいのが、表示する環境です。
GitHub 上では、
> [!IMPORTANT]
> 重要な情報が専用の Alert として表示されます。
しかし、この記法に対応していない Markdown レンダラーでは、
[!IMPORTANT]
重要な情報という普通の引用として表示される可能性があります。
そのため、GitHub README のように GitHub上で読むことを前提とした文書では使いやすい記法ですが、さまざまな Markdown 処理系で表示する文書では互換性を意識する必要があります。
まとめ
GitHub で見かける、
> [!IMPORTANT]という記法は、GitHub の Alerts と呼ばれる Markdown 拡張です。
> は標準 Markdown の引用記法ですが、[!IMPORTANT] などを特別な注意ボックスとして解釈する部分は標準 Markdown には含まれていません。
GitHub の README や Issue では、重要事項を視覚的に目立たせる方法として便利です。
利用できる種類は、
NOTE
TIP
IMPORTANT
WARNING
CAUTIONの5種類です。
README に重要な注意事項を書くときは、単純な太字だけでなく、この Alerts 記法を使うと情報の優先度をより分かりやすく伝えられます。