GitHub Markdown Alerts: NOTE, TIP, and WARNING Explained

Quick answer (one-paragraph TL;DR)

GitHub Markdown alerts are a blockquote syntax — > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], and > [!CAUTION] — that GitHub renders as a colored, iconed callout instead of a plain quote block. Write the label on its own blockquote line, then the message underneath it:

> [!TIP]
> Commit early and often — small commits are easier to review.

That's the whole feature. One catch is worth knowing up front: this is a GitHub-specific extension, not standard Markdown, so it only looks right on GitHub's own pages.

How it actually works

The exact syntax

Each alert is a normal blockquote — every line starts with > — where the first line is a type marker in square brackets, and the rest of the block is the message:

> [!NOTE]
> Useful context the reader should catch even when skimming.

> [!WARNING]
> This will overwrite the file without asking. Back it up first.

The marker has to match one of the five recognized types exactly, and it needs to sit on its own line at the top of the blockquote. There's no way to customize the label text, and no room for a sixth type.

The five alert types and when each fits

GitHub documents a specific purpose for each type. NOTE is for useful information worth catching even on a skim. TIP is optional advice that makes a task easier, not required to succeed. IMPORTANT is information the reader needs to reach their goal. WARNING flags something urgent that needs immediate attention to avoid a problem. CAUTION calls out the risk of a negative or destructive outcome — the strongest of the five.

Picking the right one is a small but real editorial call, the same judgment you'd apply in a Markdown style guide for technical docs. A WARNING that fires on every page trains readers to skip warnings.

How it got here

The feature started as a May 2022 beta supporting only Note and Warning, with a case-sensitive **Note**/**Warning** label format. GitHub added Tip and Caution in November 2023, then officially launched all five types in December 2023. Along the way, the rendering moved from a misused blockquote to a properly styled block with its own icon and color — a cleaner fix than the earlier version, which leaned on blockquote HTML for something that wasn't really a quote.

When to use it (and when to skip it)

Where it actually renders

The alert styling shows up on GitHub's own surfaces: Issues, pull requests, Discussions, Gists, Releases, and Markdown files viewed on github.com, including a repo's README. Open that same file somewhere else — a plain CommonMark parser, most static site generators, a third-party Markdown viewer — and the styling doesn't travel with it. You'll see a literal [!NOTE] line inside an ordinary gray blockquote instead of a colored callout. If a README needs to look right both on GitHub and on a docs site built from the same file, alerts are a real portability trade-off worth knowing before you write a dozen of them.

GitHub extension, not a spec

This syntax never went into CommonMark. When GitHub proposed it, the CommonMark community pushed back specifically on baking English words into the markup — a syntax like [!NOTE] doesn't translate cleanly. Other tools had already solved the same problem their own way: other note-taking apps and Microsoft Docs use similar bracket syntax, Docusaurus has its own directive format, and reStructuredText has had typed admonitions for years. GitHub's version is one dialect among several, not the one true way to write a callout. That matters if you care about general Markdown blockquotes and callouts staying portable, or if you're maintaining something like a CHANGELOG.md your team will actually read that also has to render outside GitHub.

Use it sparingly

GitHub's own style guidance caps alerts at one or two per document, says never to nest one inside another element, and says not to place two back-to-back. Think of an alert as an interruption you're asking the reader to make. Save it for the one or two things in a document that genuinely need it.

Frequently Asked Questions

What's the difference between NOTE, TIP, IMPORTANT, WARNING, and CAUTION?

Each maps to a different urgency level: NOTE is useful context worth catching even when skimming; TIP is optional advice that makes a task easier; IMPORTANT is information the reader needs to succeed; WARNING flags something urgent that needs immediate attention; CAUTION calls out a risk of a negative or destructive outcome. Picking the right one signals intent at a glance.

Do GitHub alerts render outside of GitHub?

Not reliably. The > [!NOTE] syntax is a GitHub Flavored Markdown extension, not part of the CommonMark spec, so it only renders as a styled callout on GitHub's own surfaces — Issues, pull requests, Discussions, Gists, Releases, and Markdown files viewed on github.com. Open the same file in a plain CommonMark renderer, a different static site generator, or most third-party Markdown viewers, and it falls back to a plain blockquote with the [!NOTE] text showing literally.

Can you nest an alert inside another element, like a list or another blockquote?

No. GitHub alerts can't be nested inside other elements, and GitHub's own guidance says to avoid placing two alerts back-to-back. Treat an alert as a top-level block on its own, not a component you compose into other Markdown structures.

How many alerts should one document use?

Sparingly — GitHub's own guidance caps it at one or two per document. Alerts are meant to interrupt a skim for something that genuinely needs it. A page with five or six loses that effect and starts to read like every paragraph is shouting.

Doing this with Carets

If you're writing a README or a docs file headed for GitHub, you're writing plain Markdown — and that's exactly what Carets is built for. It's a fast, native Markdown and code editor for iPhone, iPad, and Mac, so the file you draft is the same plain-text file GitHub will render, with syntax highlighting while you write the fenced examples above. Files, projects, and tags keep a docs folder organized alongside the rest of a repo's writing, whether you're drafting on a laptop or picking a thought back up on an iPad.

One thing worth being straight about: Carets doesn't render GitHub's colored alert boxes in the editor. It's a fast, native place to write and organize the plain-text source, not a live GitHub-alert previewer — for that, you're checking the rendered file on github.com like everyone else.

Carets is available on the App Store for iPhone, iPad, and Mac.