An admonition is a styled callout block that draws attention to a particular piece of content — a tip, a warning, a note, or similar. Admonitions are not part of the original Markdown specification; they are extensions added by specific platforms and tools.
> [!NOTE]
> This is a note admonition.
> [!TIP]
> This is a tip admonition.
> [!WARNING]
> This is a warning admonition.
Note
This is a note admonition.
Tip
This is a tip admonition.
Warning
This is a warning admonition.
Best Practice
- Use admonitions sparingly — overuse dilutes their impact and makes a page feel cluttered.
- Match the type to the content: use Note for supplementary context, Tip for helpful shortcuts, Warning for potential mistakes, and Caution for irreversible actions.
- Keep admonition content brief. Long paragraphs inside a callout are harder to scan than a short, pointed sentence.
- Write complete, standalone content inside an admonition — do not rely on surrounding context to make it meaningful.
- Use syntax that matches your target renderer — admonition syntax is not portable between platforms (GFM
[!NOTE], Obsidian callouts, and Docusaurus:::fences are mutually incompatible). - Do not use admonitions as a substitute for good prose structure. If a point is important enough to appear in the main flow, write it there.
Notes
GitHub Flavored Markdown Syntax
GitHub introduced the [!TYPE] blockquote syntax in 2023. It is now one of the most widely recognised admonition formats:
> [!NOTE]
> Useful information that readers should pay attention to.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information necessary for users to succeed.
> [!WARNING]
> Urgent information about potential risks or breaking changes.
> [!CAUTION]
> Advice about risks or negative outcomes of certain actions.
GitHub renders each type with a distinct icon and colour. Other renderers that support this syntax include Obsidian, VS Code (with extensions), and some static site generators.
Obsidian Callout Syntax
Obsidian uses a similar blockquote-based syntax with a wider range of built-in types:
> [!info]
> This is an info callout.
> [!warning] Watch out
> You can add a custom title after the type keyword.
> [!tip]- Collapsible tip
> Adding a `-` after the type makes the callout collapsible.
The type keyword is case-insensitive. A custom title can follow the type on the same line. A - suffix makes the callout collapsible by default; + makes it expanded by default.
Emoji-Based Admonitions
Some lightweight conventions use emoji to signal intent, particularly in README files and wikis where no renderer-specific extension is available:
> 📝 **Note:** This approach works in any Markdown renderer.
> ⚠️ **Warning:** No special rendering — just a blockquote with an emoji.
> 💡 **Tip:** Useful when targeting a plain renderer like a basic wiki.
This approach is purely visual — there is no semantic difference between types. It degrades gracefully to a plain blockquote in any renderer.
Docusaurus Admonition Syntax
Docusaurus uses fenced ::: divs with a type keyword:
:::note
This is a note.
:::
:::tip My custom title
This tip has a custom title.
:::
:::warning
This is a warning.
:::
Markdown Flavour Support
Admonitions are a non-standard extension. Support varies widely by platform.
Flavour Support Detail
| Flavour / Platform | Syntax | Notes |
|---|---|---|
| Original Markdown | None | Not supported. |
| CommonMark | None | Not in the spec. |
| GitHub Flavored Markdown | > [!TYPE] |
Supported since 2023. Five types: NOTE, TIP, IMPORTANT, WARNING, CAUTION. |
| Pandoc Markdown | None natively | Can be approximated with fenced divs and custom templates. |
Practical Examples
- Reminding readers of something before a recipe step: A note before a tricky step saves confusion later.
> [!NOTE]
> Make sure your butter is at room temperature before you start — cold butter will not cream properly.
Note
Make sure your butter is at room temperature before you start — cold butter will not cream properly.
- Sharing a time-saving shortcut in a travel guide: A tip mid-page lets experienced readers pick up something useful without interrupting the main flow.
> [!TIP]
> Booking the morning ferry gives you the whole day on the island. The afternoon crossing often sells out in summer.
Tip
Booking the morning ferry gives you the whole day on the island. The afternoon crossing often sells out in summer.
- Warning readers before something that cannot be undone: A warning immediately before an irreversible step gives readers a moment to pause.
> [!WARNING]
> Once you click Delete, your post is permanently removed and cannot be recovered.
Warning
Once you click Delete, your post is permanently removed and cannot be recovered.