If you spend any time reading READMEs on GitHub, you have probably noticed those colored callout boxes — blue for notes, green for tips, purple for important, yellow for warnings, red for caution. They stand out in a sea of plain text, and for good reason: they are meant to. GitHub added official support for these alert blocks in December 2023, giving them a name ("alerts") and a clean syntax. Before that, developers were faking them with emoji, HTML tables, and SVG hacks.
This guide covers everything you need to know to use GitHub alerts well: the exact syntax, all five types, where they actually render, the real limitations you will hit, and a practical example of putting them to work in a README.
The Basic Syntax
GitHub alerts are built on top of standard Markdown blockquote syntax. A blockquote that starts with [!KEYWORD] on the first line — and only the first line — is treated as an alert.
> [!NOTE]
> Useful information that users should know, even when skimming.
The > prefix is required on every line of the alert body, just like a normal blockquote. The keyword must be uppercase and must appear alone on that first line with nothing before or after it inside the brackets. Any content that follows on subsequent >-prefixed lines becomes the alert body, and standard Markdown formatting — bold, inline code, links — works inside the body.
Multi-line bodies work exactly as you would expect:
> [!WARNING]
> This will permanently delete your data.
> Make sure you have a backup before continuing.
> See the [backup guide](https://example.com) for details.
All Five Alert Types
As of 2026, GitHub supports exactly five alert keywords. No others — not [!EXAMPLE], [!QUESTION], or [!SPOILER], despite community requests for them. Here are the five, along with GitHub's own descriptions of when to use each one.
NOTE
Renders with a blue information icon. Use it for information that is useful but not urgent — something a reader skimming the page should still catch.
> [!NOTE]
> This package requires Node.js 18 or later.
TIP
Renders with a green lightbulb icon. Use it for helpful advice that makes a task easier or more efficient, but is not required for success.
> [!TIP]
> Run `npm run dev --open` to automatically open the browser on startup.
IMPORTANT
Renders with a purple speech-bubble icon. Use it for information the reader must know to accomplish their goal. It sits a notch above NOTE in severity without implying danger.
> [!IMPORTANT]
> You must set `GITHUB_TOKEN` in your environment before running the deploy script.
WARNING
Renders with a yellow/orange warning triangle. Use it for urgent information that could cause problems if ignored.
> [!WARNING]
> Downgrading from v2 to v1 is not supported and will corrupt your database schema.
CAUTION
Renders with a red octagon icon. Use it for the most severe cases — actions with risky or irreversible negative outcomes.
> [!CAUTION]
> Running this script in production will immediately terminate all active user sessions.
A Practical Example: A README Install Section
Here is how you might use several alert types together in a real README, without overdoing it:
## Installation
Install dependencies:
```bash
npm install
```
> [!NOTE]
> This project uses [pnpm workspaces](https://pnpm.io/workspaces). Running `npm install`
> at the root installs dependencies for all packages.
Copy the example environment file and fill in your values:
```bash
cp .env.example .env
```
> [!IMPORTANT]
> Never commit your `.env` file. It is listed in `.gitignore` but double-check before pushing.
Start the development server:
```bash
npm run dev
```
> [!WARNING]
> The dev server binds to `0.0.0.0` by default. Do not run it on a shared or public network
> without configuring a firewall rule first.
Three alerts across a medium-length section is already on the high end. GitHub's own documentation recommends limiting alerts to one or two per document, and never placing them back-to-back. When everything is highlighted, nothing is.
Where Alerts Render
GitHub alerts are a GitHub-specific extension of Markdown. They render on github.com in these contexts:
- Repository README files (in the repo file browser view)
- Issue bodies and comments
- Pull request descriptions and review comments
- GitHub Discussions posts
- GitHub Wiki pages
GitHub's mobile apps also support rendering alerts as of 2024.
However, alerts do not render natively in several places you might expect:
- GitHub Pages: Static sites built through GitHub Pages (including the default Jekyll processor) treat alert blockquotes as plain blockquotes. You need a separate plugin — for Jekyll, third-party gems handle this; for other generators, npm packages like
rehype-github-alertsormarkdown-it-github-alertsreplicate the styling. - VS Code's built-in Markdown preview: The standard preview pane does not support GitHub's alert extension. You will see a plain blockquote. Some VS Code extensions add support, but it is not built in.
- GitLab: GitLab has its own admonition syntax using a different convention (
::: notestyle), so GitHub-style alerts will not render styled there. - The GitHub Markdown REST API in default mode: If you render Markdown via the GitHub API, you must explicitly pass
"mode": "gfm"in the request body. The default"markdown"mode treats alerts as ordinary blockquotes. - Generic Markdown editors and documentation tools: Docusaurus, MkDocs (Material theme has its own admonition syntax), Notion, and most other tools either ignore the syntax or treat it as a blockquote.
Limitations Worth Knowing
No nesting inside other block elements
Alerts cannot be placed inside list items, <details> collapsible blocks, tables, or other block-level containers. If you try, GitHub renders it as a plain blockquote. This is the limitation most people hit when trying to put a warning inside a <details>><summary>Advanced options</summary> block — it will not work.
No indented alerts
The > [!TYPE] marker must start at the beginning of a line. Indenting the blockquote — even by a single space — causes GitHub to treat it as a normal blockquote and skip the alert styling.
Only uppercase keywords
The keyword must be uppercase: [!NOTE] works, [!note] and [!Note] do not. There is no case-insensitive fallback.
No custom labels or types
You cannot change the label that appears in the rendered box, and you cannot invent your own keyword. A [!DEFINITION] or [!EXAMPLE] will render as a plain blockquote. The community has requested custom alert types and non-English labels for internationalized documentation, but as of mid-2026 GitHub has not extended the keyword set beyond the original five.
Portability concerns
Because this syntax is GitHub-proprietary, documents that rely heavily on alerts are not portable. If your README is also published as documentation on a static site, or if someone reads it locally in a Markdown editor, alerts will appear as plain blockquotes — functional, but unstyled. For projects where documentation portability matters, consider using alerts sparingly or pairing them with a static-site plugin that replicates the rendering.
The Old Syntax (Now Deprecated)
Before the December 2023 release, GitHub briefly supported a bold-text variant for notes and warnings — > **Note** and > **Warning** — that predated the bracket syntax. GitHub dropped active promotion of this approach when it shipped the five-type bracket syntax. You may still see it in older READMEs. It is worth updating those to the current [!NOTE] style if you encounter them.
A Word on Overuse
The temptation when you discover a clean-looking callout syntax is to use it for everything that feels slightly important. Resist. Alerts work because they break the visual flow of a page — that interruption is the signal. Overuse trains readers to skip them, which defeats the purpose entirely. A single [!WARNING] in a 500-line README will get read. Five of them in a row will get scrolled past.
Use [!NOTE] for genuinely useful supplementary context, [!TIP] for workflow shortcuts readers may not know about, [!IMPORTANT] for prerequisites and non-obvious requirements, [!WARNING] for real gotchas that have burned people, and [!CAUTION] for destructive or irreversible actions only. Keep them rare, keep them specific, and they will do their job.