GitHub.com の Markdown でアラート記法が変更された話

<!-- # GitHub.com の Markdown でアラート記法が変更された話 -->

GitHub.com で利用できる Markdown では、以下のようにアラートを作成する記法が 2022 年 5 月 19 日に公開されました。

https://github.com/orgs/community/discussions/16925

```markdown: 公開当初の記法
> **Note**
> This is a note

> **Warning**
> This is a warning
```

ここから約 1 年のフィードバックを経て、この記法にいくつかの変更が加わりました。本記事では、この変更とそれに伴う注意点について紹介します。

:::note info
本記事では、`**Note**` などのアラート種を指定する部分をアラートタグと呼称します。
:::

このアラート記法は GitHub Docs の [構文紹介ページ][github-alerts] にも掲載されています。（[日本語版][github-ja-alerts] では “警告” となっていますが、本記事ではアラート記法と呼称します）

[github-alerts]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts "Alerts | Basic writing and formatting syntax - GitHub Docs"
[github-ja-alerts]: https://docs.github.com/ja/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts "警告 | 基本的な書き方とフォーマットの構文 - GitHub Docs"

:::note warn
2023 年 11 月 14 日のアップデートによって、アラート種の追加やいくつかの変更がなされました。
詳細は以下の記事を参照してください。

https://qiita.com/Yarakashi_Kikohshi/items/e6802e08921388d8c6e9
:::

## 変更点

2023 年 7 月 21 日、数々のフィードバックを基に、いくつかの変更点と追加点がありました。

https://github.com/orgs/community/discussions/16925#discussioncomment-6506860

- **変更**：
    - アラートタグは case を問わない（以前はタイトルケースのみ対応していた）
    - アラートタグは Markdown や HTML の装飾を含められない
    - アラートタグのある行は独立行
    - アラートタグのみは許可されない
    - ~~アラートタグの次行に必ずテキスト行が必要~~（2023/07/28 一部修正）
    - ~~[Soft line breaks][gfm-slb] を [Hard line breaks][gfm-hlb] と解釈しない場合は、ハイライトタグの直右に “**明示的な**” 強制改行が必要~~（2023/07/28 修正）
    - パース後は `blockquote` ではなく `div` に変更
    - より視覚的に強調（2023/07/28 修正）
        |        Before         |        After         |
        | :-------------------: | :------------------: |
        | ![before-highlight][] | ![after-highlight][] |
- **追加**：
    - 新しいアラート種 “important”
    - 新たなアラートタグ記法 `[!alertType]`

[gfm-slb]: https://github.github.com/gfm/#soft-line-breaks "Soft line breaks - GitHub Flavored Markdown Spec"
[gfm-hlb]: https://github.github.com/gfm/#hard-line-breaks "Hard line breaks - GitHub Flavored Markdown Spec"

[before-highlight]: https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/cd5ba40b-087f-45b3-89bf-15eacf1d8bf1.png "2023/07/28 アップデート前の表示"
[after-highlight]: https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/973dfe43-e873-7e01-a87c-bbddc80da76a.png "2023/07/28 アップデート後の表示"

:::note alert
これまでの `**alertType**` による記法は、非推奨となり今後削除されます。`[!alertType]` に変更してください。
:::

特に、新たなアラートタグ記法 `[!alertType]` は [Obsidian][] の [Callout][obsidian-callouts] 記法に類似しています。

[obsidian]: https://obsidian.md/ "Obsidian - Sharpen your thinking"

## 追加された記法

新しいアラート種 “important” と、新たなアラートタグ記法 `[!alertType]` が追加されました。

これによって、次のように書くことが出来ます。

```markdown
> [!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.
```

<!-- ![highlight notation](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/7edab857-692e-cab3-76cd-8e159332519b.png "ハイライト記法の例") -->

![highlight notation](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/590705/6945c878-da10-c608-3db3-a6f69101b106.png "ハイライト記法の例")

したがって、現状として使えるアラートタグは計 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 warn
この節では `[!alertType]` を例にしていますが、`**alertType**` でも同様の注意が必要です。
:::
-->

----------

「アラートタグのある行は独立行」でなければなりません。
そのため次のような書き方では、アラート記法として解釈されません。

```markdown
> [!Note] This is a note!
```

`[!Note]` は独立行である必要があるため、必ず次のようにします。

```markdown
> [!Note]
> This is a note!
```

ハイライトタグが独立行でなければならない理由は、次のように説明されています。

> > @<foo>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

----------

<details>
<summary>2023 年 7 月 28 日の修正以前の注意点（折りたたみ）</summary>

「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 内でアラート記法として解釈されません。

```markdown
> [!NOTE]
> This is a note!
```

`[!NOTE]` の後ろに強制改行を付す必要があります。Markdown における強制改行は、以下の 3 つがあります。
- 連続した半角スペース 2 つの後に改行
- `\` の後に改行
- `<br>` (HTML)

また、`[!NOTE]` と強制改行の間に文字を入れることは出来ません。したがって、次のような書き方をします。

```markdown
> [!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 やコメント内で利用しても問題なく解釈されます。

このことを踏まえると、常にアラートタグの直右には強制改行を付しておくと良いと思われます。

</details>

# 余談

GitHub.com Markdown のアラート記法はいまだ β 版です。そのため、今後も変更が加えられる可能性があります。

変更等の情報発信は [GitHub Discussion][github-discussion] でのみとなっているようですが、この記法を利用している人は定期的にチェックすると良いでしょう。

[github-discussion]: https://github.com/orgs/community/discussions/16925 "[Markdown] An option to highlight a \"Note\" and \"Warning\" using blockquote (Beta) · community · Discussion #16925"

また、バグがあれば Discussion 内に報告しておくと良いでしょう。

## 他の Markdown 記法との競合

新たに追加された `[!alertType]` は、[Link reference definition][gfm-lrd] と競合します。

[gfm-lrd]: https://github.github.com/gfm/#link-reference-definitions "Link reference definition - GitHub Flavored Markdown Spec"

例えば次のように書いたとき、アラート記法は有効にならずリンクが優先されます。

```markdown
> [!Warning]
> This is a Warning!

[!warning]: https://www.example.com "Example Domain"
```

リンクの参照ラベル先頭に `!` を付す人はあまりいないと思いますが、ちょっとだけ注意が必要です。

## 類似記法

本記事で紹介したアラート記法に類似する記法は、他の Markdown サービスでも提供されています。

- Block quotes + `**alertType**`：
    - [Special attention][mdn-specialAttention] (MDN)
- Block quotes + `[!alertType]`：
    - [Alerts][mslearn-alerts] (Microsoft Learn)
    - [Callouts][obsidian-callouts] (Obsidian)

[mslearn-alerts]: https://learn.microsoft.com/en-us/contribute/markdown-reference#alerts-note-tip-important-caution-warning "Markdown reference for Microsoft Learn - Contributor guide | Microsoft Learn"
[obsidian-callouts]: https://help.obsidian.md/Editing+and+formatting/Callouts "Callouts - Obsidian Help"
[mdn-specialAttention]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#notes_warnings_and_callouts "How to write in Markdown - The MDN Web Docs project | MDN"

この手の注意を惹くための記法は、他にも以下のようなものを見つけることが出来ます。

- 連続する 3 つの `:` で囲う：
    - [Note 記法][qiita-note] (Qiita)
    - [Admonitions][docsa-admonitions] (Docusaurus)
    - [Fenced container][mdit-fencedContainer] (markdown-it)
- 連続する 3 つの `!` を使う：
    - [Admonition][pm-admonition] (Python-Markdown)
    - [Admonitions][mkdocs-admonitions] (MkDocs)

[pm-admonition]: https://python-markdown.github.io/extensions/admonition/ "Admonition — Python-Markdown 3.4.4 documentation"
[docsa-admonitions]: https://docusaurus.io/docs/markdown-features/admonitions "Admonitions | Docusaurus"
[mdit-fencedContainer]: https://github.com/markdown-it/markdown-it-container "markdown-it/markdown-it-container: Fenced container plugin for markdown-it markdown parser"
[mkdocs-admonitions]: https://squidfunk.github.io/mkdocs-material/reference/admonitions/ "Admonitions - Material for MkDocs"
[qiita-note]: https://qiita.com/Qiita/items/c686397e4a0f4f11683d#note---%E8%A3%9C%E8%B6%B3%E8%AA%AC%E6%98%8E "Markdown記法 チートシート - Qiita"