Markdown cheatsheet · Callouts
Callouts and note boxes in markdown
Markdown gained real callout syntax, but each tool spells it differently: GitHub alerts, Obsidian callouts, docs-site admonitions. Here's what renders where, and the fallback for everywhere else.
The 2026 answer is different from the old one
For years, markdown had no callouts and the advice was "use a blockquote and hope". That changed: GitHub, Obsidian and several docs tools now have real callout syntax. Most pages ranking for this question still show you the old workaround. Here's what actually renders today, by tool.
GitHub, GitLab: alerts
A blockquote whose first line is a special marker. Five types, each with its own icon and colour.
> [!NOTE] > Useful information a reader should know. > [!WARNING] > Something that needs immediate attention.
ℹ Note
Useful information a reader should know.
⚠ Warning
Something that needs immediate attention.
The five markers are [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION]. The marker must be the first line of the blockquote, in uppercase, alone.
[!WARNING] line shows up as literal text inside an ordinary quote. Great inside the GitHub/GitLab world, invisible outside it.Obsidian: callouts
Same blockquote idea, different marker, and Obsidian has far more types plus a title and a fold control.
> [!warning] Heads up > This is a collapsible callout.
⚠ Heads up
This is a collapsible callout.
Obsidian's markers are lowercase and accept a custom title after them; add a + or - ([!warning]-) to make it foldable. None of this renders on GitHub, and GitHub's uppercase form doesn't render in Obsidian, so a file that needs both is out of luck.
Docs tools: admonitions
MkDocs Material, Docusaurus, reStructuredText and others use "admonitions", with yet another syntax. MkDocs uses !!! note; Docusaurus uses a triple-colon fence:
:::tip This renders as a callout in Docusaurus. :::
Tip
This renders as a callout in Docusaurus.
The fallback that works everywhere
When the file has to look right in a renderer with no callout support, a plain blockquote with a bold label and an emoji is the lowest common denominator. No colour, but the structure and the meaning survive anywhere.
> ⚠️ **Warning:** this deletes your data.
⚠️ Warning: this deletes your data.
Which to use
| Where the file lives | Use |
|---|---|
| A GitHub / GitLab repo | Alerts: > [!WARNING] |
| An Obsidian vault | Callouts: > [!warning] Title |
| A docs site | Your generator's admonition syntax |
| Somewhere unknown, or several places | Blockquote + bold label + emoji |
Common questions
Why does [!NOTE] show up as plain text?
You're viewing it somewhere that isn't GitHub or GitLab. It's their syntax, not universal markdown.
Can I make my own callout type or colour?
On GitHub, no, the five types are fixed. In Obsidian and most docs tools, yes, via CSS or config.
What's the difference between a callout, an alert and an admonition?
Nothing, conceptually, they're the same feature under three names. Obsidian says callout, GitHub says alert, the docs world says admonition.
Do callouts work in a comment or a chat?
Almost never. Treat them as a documentation feature; for a comment, use the blockquote fallback.