DEV Community

vast cow
vast cow

Posted on

What is the "Alerts" Syntax You Can Use in GitHub Markdown?

When reading GitHub READMEs or Issues, you may come across syntax like this:

> [!IMPORTANT]
> **If you are upgrading from a previous version**
>
> The configuration method has changed.
> Please check the migration procedure before upgrading.
Enter fullscreen mode Exit fullscreen mode

This is not a regular Markdown quote; it's a Markdown extension called Alerts that GitHub supports.

On GitHub, it is displayed as a note box with icons and decorations according to the type, such as IMPORTANT.

It's Not Standard Markdown

First, it's important to understand this part:

>
Enter fullscreen mode Exit fullscreen mode

This is the standard Markdown quote syntax.

On the other hand,

[!IMPORTANT]
Enter fullscreen mode Exit fullscreen mode

is not part of the standard Markdown specification. It is interpreted as having a special meaning.

Therefore,

> [!IMPORTANT]
> This is important information.
Enter fullscreen mode Exit fullscreen mode

is a GitHub-specific extension syntax that utilizes Markdown's quote syntax.

As a result, while it may be displayed as a note box on GitHub, it may be displayed as a simple quote in other Markdown renderers.

Alert Types You Can Use

GitHub mainly supports the following five types of Alerts:

NOTE

Use this to indicate supplementary information.

> [!NOTE]
> This setting is optional.
Enter fullscreen mode Exit fullscreen mode

TIP

Use this to indicate convenient methods or recommended ways of doing things.

> [!TIP]
> You can easily check the settings using this command.
Enter fullscreen mode Exit fullscreen mode

IMPORTANT

Use this for important information that users should definitely know.

> [!IMPORTANT]
> Back up your configuration file before upgrading.
Enter fullscreen mode Exit fullscreen mode

WARNING

Use this to alert users to operations that may cause problems.

> [!WARNING]
> This operation will overwrite existing settings.
Enter fullscreen mode Exit fullscreen mode

CAUTION

Use this for operations that involve particularly serious risks, such as data loss.

> [!CAUTION]
> Running this command will delete saved data.
Enter fullscreen mode Exit fullscreen mode

Writing Multiple Lines

If you want to write multiple lines of text within an Alert, add a > to each line.

> [!IMPORTANT]
> The configuration method has changed.
>
> Before upgrading,
> check the new configuration method.
Enter fullscreen mode Exit fullscreen mode

If you want to insert a blank line, write:

>
Enter fullscreen mode Exit fullscreen mode

This is the same mechanism as a standard Markdown blockquote.

You Can Also Use Bold Text and Links

You can also use standard Markdown syntax within Alerts.

> [!IMPORTANT]
> **Check before upgrading**
>
> See the [Migration Guide](docs/migration.md) for details.
Enter fullscreen mode Exit fullscreen mode

This is useful when you want to guide readers to important documents in the README.

When Should You Use It?

Alerts are useful for making the text in a README easier to read and organize.

For example:

  • Notes for upgrading
  • Breaking changes
  • Security notes
  • Configuration notes
  • Common mistakes
  • Recommended settings

In particular,

## Upgrade

This describes how to upgrade.

> [!IMPORTANT]
> The configuration file format has changed in version 2 and later.

Run the following command.
Enter fullscreen mode Exit fullscreen mode

Using it this way clearly separates the main text from important information.

Be Careful Not to Overuse It

Although it is a useful syntax, if you use Alerts for all information, you will end up making it difficult to distinguish the importance of each item.

For example, if a README is filled with:

> [!NOTE]
> ...

> [!TIP]
> ...

> [!IMPORTANT]
> ...

> [!WARNING]
> ...
Enter fullscreen mode Exit fullscreen mode

like a box full of notes, it will be difficult to determine what to read.

Basically, use regular text, and use Alerts only for information you really want to highlight.

The Display May Change Outside of GitHub

Another thing to keep in mind when using this syntax is the environment in which it will be displayed.

On GitHub,

> [!IMPORTANT]
> Important information
Enter fullscreen mode Exit fullscreen mode

is displayed as a dedicated Alert.

However, in Markdown renderers that do not support this syntax, it may be displayed as a regular quote:

[!IMPORTANT]
Important information
Enter fullscreen mode Exit fullscreen mode

Therefore, while this syntax is easy to use for documents intended to be read on GitHub, such as GitHub READMEs, you need to be aware of compatibility when displaying documents in various Markdown processing systems.

Summary

The syntax you see on GitHub, such as

> [!IMPORTANT]
Enter fullscreen mode Exit fullscreen mode

is a Markdown extension called Alerts.

The > is the standard Markdown quote syntax, but the part that interprets [!IMPORTANT] and so on as a special note box is not included in standard Markdown.

On GitHub READMEs and Issues, it is a useful way to visually highlight important information.

The types you can use are:

NOTE
TIP
IMPORTANT
WARNING
CAUTION
Enter fullscreen mode Exit fullscreen mode

When writing important notes in a README, using this Alerts syntax can convey the priority of information more clearly than just using bold text.

GitHubのMarkdownで使える「Alerts」記法とは？

GitHub の README や Issue を読んでいると、次のような記法を見かけることがあります。

> [!IMPORTANT]
> **以前のバージョンからアップグレードする場合**
>
> 設定方法が変更されています。
> アップグレード前に移行手順を確認してください。
Enter fullscreen mode Exit fullscreen mode

これは通常の Markdown の引用ではなく、GitHub がサポートしている Alerts という Markdown 拡張です。

GitHub 上では、IMPORTANT のような種類に応じてアイコンや装飾が付いた注意ボックスとして表示されます。

標準Markdownではない

まず押さえておきたいのは、次の部分です。

>
Enter fullscreen mode Exit fullscreen mode

これは標準的な Markdown の引用記法です。

一方、

[!IMPORTANT]
Enter fullscreen mode Exit fullscreen mode

を特別な意味として解釈する仕組みは、標準 Markdown の仕様ではありません。

つまり、

> [!IMPORTANT]
> 重要な情報です
Enter fullscreen mode Exit fullscreen mode

という記法は、Markdown の引用構文を利用した GitHub独自の拡張記法です。

そのため、GitHub では注意ボックスとして表示されても、別の Markdown レンダラーでは単なる引用として表示される場合があります。

使用できるAlertの種類

GitHub では、主に次の5種類の Alert が利用できます。

NOTE

補足情報を示したい場合に使います。

> [!NOTE]
> この設定は省略可能です。
Enter fullscreen mode Exit fullscreen mode

TIP

便利な方法やおすすめの使い方を示す場合に使います。

> [!TIP]
> このコマンドを使うと設定を簡単に確認できます。
Enter fullscreen mode Exit fullscreen mode

IMPORTANT

ユーザーに必ず知っておいてほしい重要事項に使います。

> [!IMPORTANT]
> アップグレード前に設定ファイルをバックアップしてください。
Enter fullscreen mode Exit fullscreen mode

WARNING

問題が発生する可能性がある操作について注意を促す場合に使います。

> [!WARNING]
> この操作を行うと既存の設定が上書きされます。
Enter fullscreen mode Exit fullscreen mode

CAUTION

データ損失など、特に重大なリスクを伴う操作に使います。

> [!CAUTION]
> このコマンドを実行すると保存済みデータが削除されます。
Enter fullscreen mode Exit fullscreen mode

複数行を書く場合

Alert の中に複数行の文章を書く場合は、それぞれの行に > を付けます。

> [!IMPORTANT]
> 設定方法が変更されています。
>
> アップグレードする前に、
> 新しい設定方法を確認してください。
Enter fullscreen mode Exit fullscreen mode

空行を入れたい場合も、

>
Enter fullscreen mode Exit fullscreen mode

と書きます。

通常の Markdown の blockquote と同じ仕組みです。

太字やリンクも使える

Alert の中では、通常の Markdown 記法も利用できます。

> [!IMPORTANT]
> **アップグレードする前に確認してください**
>
> 詳細は[移行ガイド](docs/migration.md)を参照してください。
Enter fullscreen mode Exit fullscreen mode

README の中で重要なドキュメントへ誘導するときには便利です。

どんな場面で使うとよいか

Alerts は、README の文章を読みやすく整理するのに向いています。

たとえば、

  • バージョンアップ時の注意事項
  • 破壊的変更
  • セキュリティ上の注意
  • 設定時の補足
  • よくあるミス
  • 推奨設定

などです。

特に、

## Upgrade

アップグレード方法について説明します。

> [!IMPORTANT]
> バージョン2以降では設定ファイルの形式が変更されています。

次のコマンドを実行します。
Enter fullscreen mode Exit fullscreen mode

のように使うと、通常の本文と重要事項を明確に分けられます。

使いすぎには注意

便利な記法ですが、すべての情報を Alert にしてしまうと、かえって重要度が分かりにくくなります。

たとえば README が、

> [!NOTE]
> ...

> [!TIP]
> ...

> [!IMPORTANT]
> ...

> [!WARNING]
> ...
Enter fullscreen mode Exit fullscreen mode

のような注意ボックスだらけになると、どこを読むべきなのか判断しづらくなります。

基本的には通常の文章を使い、本当に目立たせたい情報だけを Alert にするのがよいでしょう。

GitHub以外では表示が変わる可能性がある

この記法を使う場合にもう一つ注意したいのが、表示する環境です。

GitHub 上では、

> [!IMPORTANT]
> 重要な情報
Enter fullscreen mode Exit fullscreen mode

が専用の Alert として表示されます。

しかし、この記法に対応していない Markdown レンダラーでは、

[!IMPORTANT]
重要な情報
Enter fullscreen mode Exit fullscreen mode

という普通の引用として表示される可能性があります。

そのため、GitHub README のように GitHub上で読むことを前提とした文書では使いやすい記法ですが、さまざまな Markdown 処理系で表示する文書では互換性を意識する必要があります。

まとめ

GitHub で見かける、

> [!IMPORTANT]
Enter fullscreen mode Exit fullscreen mode

という記法は、GitHub の Alerts と呼ばれる Markdown 拡張です。

> は標準 Markdown の引用記法ですが、[!IMPORTANT] などを特別な注意ボックスとして解釈する部分は標準 Markdown には含まれていません。

GitHub の README や Issue では、重要事項を視覚的に目立たせる方法として便利です。

利用できる種類は、

NOTE
TIP
IMPORTANT
WARNING
CAUTION
Enter fullscreen mode Exit fullscreen mode

の5種類です。

README に重要な注意事項を書くときは、単純な太字だけでなく、この Alerts 記法を使うと情報の優先度をより分かりやすく伝えられます。

Top comments (0)