GitHub Alerts in Markdown: NOTE, TIP, WARNING and More

What are GitHub alerts?

GitHub alerts are highlighted boxes in Markdown, also called callouts or admonitions. They are written as a blockquote whose first line names the alert type. On GitHub they appear with a colour and an icon, so a warning stands out from the text around it.

They are a GitHub extension to Markdown, not part of the original syntax. That matters when the same file is read somewhere else, as described below.

How do I write a GitHub alert?

Start a blockquote with the alert type in square brackets and an exclamation mark, then write the message on the following quoted lines:

> [!NOTE]
> The example files are fictional.

> [!WARNING]
> Back up the folder before you move it.

GitHub's writing and formatting documentation lists five types:

Type	Use it for
`[!NOTE]`	Useful information readers should notice even when skimming.
`[!TIP]`	Advice for doing something better or more easily.
`[!IMPORTANT]`	Information needed to succeed.
`[!WARNING]`	Something that needs attention to avoid problems.
`[!CAUTION]`	Risks or negative outcomes of an action.

The same documentation recommends using alerts sparingly, at most one or two per article and not one after another, and notes that alerts can't be nested inside other elements.

Why does my alert show as `[!NOTE]` text?

If a viewer doesn't support GitHub alerts, it still understands the blockquote, so you see an ordinary quote that begins with the literal text [!NOTE]. Nothing is lost: the message is readable, just not highlighted.

Check these before assuming the viewer is the problem:

The marker is on its own line. > [!NOTE] must be the first line of the blockquote, with the message on the lines after it.
The type is one of the five. GitHub renders NOTE, TIP, IMPORTANT, WARNING and CAUTION.
The quote isn't inside a list or another block. Alerts can't be nested.

Where do GitHub alerts render?

GitHub renders them in Markdown files, issues, pull requests and discussions.
Aero Markdown renders GitHub alerts when you read a local file.
QLMarkdown, a Quick Look extension, has a GitHub alert option for Finder previews.
Obsidian has its own callouts with a similar > [!note] syntax and more types. A note written with Obsidian-only callout types may not render as an alert elsewhere; see reading Obsidian files in another app.
Other editors and viewers vary. If the alert matters, open the file in the app your readers will use and check.

Keep alerts portable

If a document travels between GitHub, editors and readers, stick to the five GitHub types, keep each alert short and make sure the sentence still makes sense as a plain quote. A reader who sees [!WARNING] as text should still understand the warning.

For other GitHub-specific syntax that can look different on your Mac, see why a README can look different on GitHub and on your Mac.