Markdown Alert Syntax Tutorial

What is Markdown Alert

When writing documentation, some content needs to stand out — things like "this operation is irreversible" or "use the command line approach." Regular paragraphs are easy for readers to skim past, but wrapping that text in a colored box with an icon changes things completely.

That's what Markdown Alert (also called callout, admonition, or notice block) is for.

Here's the thing that confuses a lot of people: native Markdown doesn't have an Alert syntax element. This is fundamentally a GitHub extension built on top of blockquotes. So this syntax primarily works on GitHub — including READMEs, Issues, PR descriptions, and Discussions. Other platforms like GitLab or Obsidian may or may not support it, which we'll cover later.

GitHub Alert Syntax Explained

GitHub officially launched this Alert syntax in late 2023, supporting five types:

TypeKeywordPurposeColor
NOTE[!NOTE]Information users should noticeBlue
TIP[!TIP]Helpful suggestionsGreen
IMPORTANT[!IMPORTANT]Critical must-read contentPurple
WARNING[!WARNING]Risks to watch out forOrange
CAUTION[!CAUTION]Potential negative consequencesRed

Basic Syntax

The format is simple — start with a blockquote >, followed by [!TYPE], then write content on the next line starting with >:

> [!NOTE]
> This is a note with information that's useful to know.

This renders as a blue box with a blue icon. Each type uses the same structure, just swap the keyword in brackets:

> [!TIP]
> Try using Ctrl+Shift+V to paste with formatting preserved.
> [!WARNING]
> This deletion cannot be undone. Please confirm before proceeding.
> [!IMPORTANT]
> Back up your database before upgrading.
> [!CAUTION]
> Modifying production config directly may cause service disruption.

Honestly, the syntax itself is just a few lines, but it makes a real difference when used in the right places.

Multi-line Content

If your alert has multiple lines, each line must start with >:

> [!WARNING]
> This operation will cause the following effects:
> 1. All existing caches will be invalidated
> 2. Users will need to re-login
> 3. Some historical data may be lost

I ran into this exact issue when writing migration docs for a project — forgot the > on one line in the middle, and that paragraph ended up outside the alert box. Made the doc look messy. So when writing multi-line alerts, double-check every line.

Using Markdown Formatting Inside Alerts

You're not limited to plain text inside alerts. Regular Markdown formatting works:

> [!TIP]
> Use `git rebase -i` to clean up your commit history, especially when you have multiple **WIP** commits.
> See the [Git documentation](https://git-scm.com/docs/git-rebase) for details.

Bold, inline code, and links all work fine. Lists inside alerts can be a bit inconsistent with indentation though, so it's best to keep things simple.

Custom Titles (Optional)

On some platforms that support GitHub Alerts, you can add a custom title after the type keyword:

> [!NOTE] Version Compatibility
> The current version only supports Node.js 18 and above.

This custom title feature isn't universally supported though. GitHub officially supports the five standard types with their default titles, and custom title rendering may vary. If it doesn't work, stick with the default.

When to Use Each Type

Many people just use NOTE for everything. Each type actually has its own semantic meaning and use case:

NOTE — for supplementary info and background that's "nice to know." Like telling readers about a feature limitation or explaining a design decision.

TIP — for optional suggestions and more efficient approaches. Like recommending a shortcut or a better tool configuration. It's not a rule to follow, but rather "you'd be better off doing this."

IMPORTANT — for rules and prerequisites that must be known. The difference from NOTE: if you skip IMPORTANT content, things will likely break later. Like "install dependencies before running" or "Python 3.10+ only."

WARNING — for actions that might cause problems but can be avoided. Like "make sure you've merged before deleting the branch" or "this API is deprecated, consider migrating."

CAUTION — for actions with potentially severe consequences. This is the highest level, for "there's no going back" situations. Like "operating directly on the production database" or "deleting unrecoverable data."

My advice: don't overuse alerts. Three to five per page is plenty. More than that and readers develop "banner blindness" — they stop noticing them entirely.

Old vs New Syntax Comparison

If you've seen GitHub's callout feature before, you might have encountered a different syntax:

> **Note**
> This is a note message.

This was the Beta syntax from 2022. The new syntax is:

> [!NOTE]
> This is a note message.

Both still render on GitHub, but the differences are significant:

AspectOld > **Note**New > [!NOTE]
LaunchMay 2022 (Beta)Dec 2023 (Official)
Type markerBold textBracket notation
Multi-lineRequires extra blank linesJust add > per line
CompatibilityGitHub onlyGitHub + other platforms
Title displayTitle and content may mergeStable formatting

When I migrated several projects from the old to new syntax, the biggest takeaway was: old syntax multi-line handling was genuinely unstable. The title and body text would occasionally end up on the same line, requiring a manual blank > line to separate them. The new syntax doesn't have this issue.

If you're still using the old syntax, switch when you can. The new syntax is simpler to write and less error-prone.

What People Did Before Alerts

Before GitHub's official Alert feature, the community came up with several workarounds. Understanding these helps explain why Alerts became so popular.

Table + Emoji Approach

Using a single-column table with emoji to simulate an alert box:

| ⚠️ **Warning** |
|:---|
| Deletion cannot be undone |

This does render as a bordered area on GitHub, but it's semantically a table, not a "notice." Style control is minimal, and there's no way to distinguish between severity levels.

HTML Approach

Embedding HTML directly in Markdown:

<div style="background: #fff3cd; padding: 10px; border-left: 4px solid #ffc107;">
<strong>⚠️ Warning:</strong> Deletion cannot be undone.
</div>

This works on regular web pages, but GitHub strips most HTML style attributes for security reasons. So style attributes basically have no effect on GitHub.

Blockquote + Bold Text

The most basic approach — blockquote with bold text:

> **Warning:** Deletion cannot be undone.

This renders everywhere Markdown is supported, but there's no color differentiation. It just looks like a regular blockquote — not very attention-grabbing.

The reason GitHub Alerts are so popular is simple: they solve the pain points of all these workarounds — colored boxes with icons, simple syntax, and it's an officially supported feature.

Compatibility: Which Platforms Support It

This is a common concern. Here's the current status of the [!NOTE] syntax:

Fully supported:

  • GitHub (READMEs, Issues, PRs, Discussions, Gists) — native support, best rendering

Supported via plugins/config:

  • Obsidian — has its own callout syntax, > [!NOTE] format is compatible
  • VS Code preview — requires a markdown-it plugin (like markdown-it-github-alerts)
  • Static site generators — Hugo, VitePress, Docusaurus can support via markdown-it plugins

Unknown / Not supported:

  • GitLab — no native support, renders as plain blockquote
  • Bitbucket — not supported
  • Standard Markdown editors (Typora, MacDown, etc.) — depends on whether the editor implements this extension

If your content is only viewed on GitHub, use Alerts freely. If your docs need to work across platforms, check the rendering on non-GitHub platforms first, or keep a fallback approach (plain blockquotes as backup).

Practical Tips

After using GitHub Alerts for over a year, here are some habits I've developed:

First, pick the right type. I once saw a project that used CAUTION (red) for every single callout. Reading that doc felt terrifying. Most of the time NOTE and TIP are sufficient — save WARNING and CAUTION for things that genuinely need attention.

Second, keep it brief. Alert text shouldn't be long. If you need three paragraphs to explain something in an alert, it probably belongs in the body text. Ideally, one or two sentences per alert.

Third, placement matters. Put alerts before the related action, not after. A warning like "back up before running the delete command" should appear before the command, so readers see the warning first.

Fourth, don't nest alerts. Putting an alert inside another alert renders oddly. If you need layered emphasis, put the important one in the alert and express the secondary point in regular text or a list.

FAQ

Why isn't my Alert rendering with styles?

The three most common reasons:

  1. [!NOTE] must be on its own line — the type marker takes one line, content starts on the next line
  2. Content lines must have > at the very start — no spaces before the >
  3. You're not on GitHub — other platforms may not support this syntax

Can I define custom types?

No. GitHub currently only supports NOTE, TIP, IMPORTANT, WARNING, and CAUTION. If you write [!INFO] or [!DANGER], it won't be recognized as an Alert and will render as a plain blockquote.

Can I put code blocks inside an Alert?

Yes, but stick to inline code (backticks) rather than multi-line code blocks. Multi-line code block indentation inside alerts can be unreliable, especially across different editor previews.

References