GitHub.com で利用できる Markdown では、以下のようにアラートを作成する記法が 2022 年 5 月 19 日に公開されました。
> **Note**
> This is a note
> **Warning**
> This is a warning
ここから約 1 年のフィードバックを経て、この記法にいくつかの変更が加わりました。本記事では、この変更とそれに伴う注意点について紹介します。
本記事では、**Note** などのアラート種を指定する部分をアラートタグと呼称します。
このアラート記法は GitHub Docs の 構文紹介ページ にも掲載されています。（日本語版 では “警告” となっていますが、本記事ではアラート記法と呼称します）
2023 年 11 月 14 日のアップデートによって、アラート種の追加やいくつかの変更がなされました。
詳細は以下の記事を参照してください。
https://qiita.com/Yarakashi_Kikohshi/items/e6802e08921388d8c6e9
変更点
2023 年 7 月 21 日、数々のフィードバックを基に、いくつかの変更点と追加点がありました。
-
変更：
- アラートタグは case を問わない（以前はタイトルケースのみ対応していた）
- アラートタグは Markdown や HTML の装飾を含められない
- アラートタグのある行は独立行
- アラートタグのみは許可されない
-
アラートタグの次行に必ずテキスト行が必要（2023/07/28 一部修正） -
Soft line breaks を Hard line breaks と解釈しない場合は、ハイライトタグの直右に “明示的な” 強制改行が必要（2023/07/28 修正） - パース後は
blockquoteではなくdivに変更 - より視覚的に強調（2023/07/28 修正）
Before After 
-
追加：
- 新しいアラート種 “important”
- 新たなアラートタグ記法
[!alertType]
これまでの **alertType** による記法は、非推奨となり今後削除されます。[!alertType] に変更してください。
特に、新たなアラートタグ記法 [!alertType] は Obsidian の Callout 記法に類似しています。
追加された記法
新しいアラート種 “important” と、新たなアラートタグ記法 [!alertType] が追加されました。
これによって、次のように書くことが出来ます。
> [!NOTE]
> Highlights information that users should take into account, even when skimming.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.
> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.
したがって、現状として使えるアラートタグは計 6 つあります。
-
**note**、**warning**、**important** -
[!note]、[!warning]、[!important]
ただし、今回の変更によって以前までの記法が使えなくなることが予告されています。
A new syntax,
[!NOTE], has been added, which will gradually replace the old one. However, the old syntax will continue to work for some time.https://github.com/orgs/community/discussions/16925#discussioncomment-6506860
そのため、現在 **Note**・**Warning** としている箇所を [!Note]・[!Warning] に変更する必要があります。
変更に伴う注意点
今回の変更で注意するべき点は、以下の 1 点です。
- アラートタグのある行は独立行
-
Soft line breaks を Hard line breaks と解釈しない場合は、“明示的な” 強制改行が必要（2023/07/28 修正）
「アラートタグのある行は独立行」でなければなりません。
そのため次のような書き方では、アラート記法として解釈されません。
> [!Note] This is a note!
[!Note] は独立行である必要があるため、必ず次のようにします。
> [!Note]
> This is a note!
ハイライトタグが独立行でなければならない理由は、次のように説明されています。
@Corentin-Lcs it's intended not to have anything other than the type in the first line. That way we could still add support for custom titles in the future. The title line now also has a special treatment to better work in variation with different font-sizes (comments vs. markdown files) in combination with an icon. Thanks.
https://github.com/orgs/community/discussions/16925#discussioncomment-6575131
2023 年 7 月 28 日の修正以前の注意点（折りたたみ）
「Soft line breaks を Hard line breaks と解釈しない場合は、“明示的な” 強制改行が必要」です。
GitHub.com における「Soft line breaks を Hard line breaks と解釈しない」とは、Markdown ソース内での改行を半角スペースとして解釈することを指します。また、Soft line breaks を Hard line breaks と解釈しない Markdown のテキスト領域は、Markdown ファイルと Gist が対応しています。
すなわち上記の注意点の意味するものは、レポジトリ内の Markdown ファイルや Gist 内では 必ずアラートタグの後ろで強制改行しなければならない と言うことです。
そのため次のような書き方では、Markdown ファイルや Gist 内でアラート記法として解釈されません。
> [!NOTE]
> This is a note!
[!NOTE] の後ろに強制改行を付す必要があります。Markdown における強制改行は、以下の 3 つがあります。
- 連続した半角スペース 2 つの後に改行
-
\の後に改行 -
<br>(HTML)
また、[!NOTE] と強制改行の間に文字を入れることは出来ません。したがって、次のような書き方をします。
> [!NOTE]
> This is a note!
> [!NOTE]\
> This is a note!
> [!NOTE]<br>
> This is a note!
この書き方は、Soft line breaks を Hard line breaks として解釈する Issues・PRs・Discussions やコメント内で利用しても問題なく解釈されます。
このことを踏まえると、常にアラートタグの直右には強制改行を付しておくと良いと思われます。
余談
GitHub.com Markdown のアラート記法はいまだ β 版です。そのため、今後も変更が加えられる可能性があります。
変更等の情報発信は GitHub Discussion でのみとなっているようですが、この記法を利用している人は定期的にチェックすると良いでしょう。
また、バグがあれば Discussion 内に報告しておくと良いでしょう。
他の Markdown 記法との競合
新たに追加された [!alertType] は、Link reference definition と競合します。
例えば次のように書いたとき、アラート記法は有効にならずリンクが優先されます。
> [!Warning]
> This is a Warning!
[!warning]: https://www.example.com "Example Domain"
リンクの参照ラベル先頭に ! を付す人はあまりいないと思いますが、ちょっとだけ注意が必要です。
類似記法
本記事で紹介したアラート記法に類似する記法は、他の Markdown サービスでも提供されています。
- Block quotes +
**alertType**：- Special attention (MDN)
- Block quotes +
[!alertType]：
この手の注意を惹くための記法は、他にも以下のようなものを見つけることが出来ます。
- 連続する 3 つの
:で囲う：- Note 記法 (Qiita)
- Admonitions (Docusaurus)
- Fenced container (markdown-it)
- 連続する 3 つの
!を使う：- Admonition (Python-Markdown)
- Admonitions (MkDocs)