Markdown Callout: Notes, Warnings, and Alerts

A markdown callout (also called an admonition or alert) is a visually distinct block that highlights important information like notes, warnings, tips, or cautions. GitHub uses > [!NOTE] syntax, Obsidian uses > [!info] syntax, and MkDocs uses !!! admonitions. This guide covers the callout syntax for each platform and shows you how to use them effectively in your documentation.

What Is a Markdown Note or Callout?

A markdown note is a blockquote-based syntax extension that renders as a colored box with an icon. Standard CommonMark does not include callouts, so each platform implements its own syntax. The result is similar across platforms: a highlighted block that draws attention to important information.

GitHub added its > [!NOTE] syntax (called "alerts") in 2023 and supports five alert types. Obsidian supports 13 callout types, most with aliases, plus custom titles and folding. MkDocs supports admonitions through the Python-Markdown admonition extension.

GitHub Alert Syntax

GitHub's alert syntax builds on blockquotes. Start with > followed by one of five alert keywords in brackets:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Each alert type renders with a distinct color and icon:

Alert Type	Color	Icon	Best For
NOTE	Blue	Info circle	Background information, context
TIP	Green	Lightbulb	Best practices, shortcuts
IMPORTANT	Purple	Message	Critical context, prerequisites
WARNING	Yellow	Triangle	Potential issues, deprecations
CAUTION	Red	Stop sign	Dangerous actions, data loss risks

The alert keyword must be on its own line immediately after >. Content starts on the next line with > prefix. You can include multiple paragraphs, code blocks, and lists inside the alert.

Multi-paragraph GitHub alert:

> [!WARNING]
> This action cannot be undone.
>
> Make sure you have a backup before proceeding.
>
> ```bash
> cp -r data/ data-backup/
> ```

Obsidian Callout Syntax

Obsidian callouts (covered alongside its other extensions in the Obsidian markdown cheat sheet) use a similar but more flexible syntax. The type goes inside [!type] and supports custom titles and folding:

> [!info] Custom Title Here
> This is an info callout with a custom title.

> [!warning]
> Default title: "Warning"

> [!tip]- Click to expand
> This callout starts collapsed. The minus sign after the type makes it foldable and closed by default.

> [!tip]+ Click to collapse
> This callout starts expanded. The plus sign makes it foldable and open by default.

Obsidian documents these callout types (colors depend on your theme):

Type	Aliases
note
abstract	summary, tldr
info
todo
tip	hint, important
success	check, done
question	help, faq
warning	caution, attention
failure	fail, missing
danger	error
bug
example
quote	cite

You can also nest callouts inside each other on Obsidian:

> [!question] Can you nest callouts?
>> [!success] Yes!
>> You can nest callouts in Obsidian by adding more `>` characters.

MkDocs Admonition Syntax

MkDocs (the Python documentation generator) uses a different syntax entirely. With the admonition extension enabled, you use three exclamation marks:

!!! note "Custom Title"
    This is a note admonition.
    Content is indented by 4 spaces.

!!! warning
    Default title is "Warning."

??? tip "Collapsible Tip"
    Use ??? for collapsible admonitions.
    This starts collapsed.

???+ example "Open by Default"
    Use ???+ for collapsible admonitions that start open.

MkDocs admonitions do not use blockquote syntax. They rely on the indentation-based approach. The !!! form needs the Python-Markdown admonition extension enabled in mkdocs.yml; the collapsible ??? form additionally needs pymdownx.details.

How to Choose the Right Callout Type

Picking the right callout type improves scannability. Readers learn to associate colors and icons with urgency levels. Here are guidelines from our experience writing documentation:

Use NOTE for context that helps but is not critical. "Note: This feature requires Python 3.10 or later."

Use TIP for best practices and efficiency suggestions. "Tip: Use keyboard shortcuts to speed up your workflow."

Use IMPORTANT for prerequisites or setup steps. "Important: Run npm install before starting the development server."

Use WARNING for potential problems that can be avoided. "Warning: Changing this setting requires restarting the application."

Use CAUTION for actions with irreversible consequences. "Caution: Deleting your account permanently removes all data."

Avoid overusing callouts. If every paragraph has a callout, none of them stand out. Limit yourself to 2 to 4 callouts per page for maximum impact.

Platform Compatibility for Callouts

Feature	GitHub	Obsidian	MkDocs	CommonMark
Basic callouts	Yes	Yes	Yes (extension)	No
Custom titles	No	Yes	Yes	No
Foldable/collapsible	No	Yes	Yes (extension)	No
Nesting	No	Yes	Yes (indent)	No
Number of types	5	13	12	0

Static site generators such as Hugo and Jekyll depend on the theme or a plugin, so check your theme's documentation before relying on callouts there.

If you need cross-platform compatibility, use GitHub's 5 alert types as your baseline (see the GitHub markdown cheat sheet for the rest of GitHub's extensions). They cover the most common use cases, and you can convert them to other formats with minimal effort.

Common Mistakes with Markdown Callouts

Mistake 1: Using the wrong syntax for the platform.

GitHub uses > [!NOTE] (uppercase, inside blockquote). Obsidian uses > [!note] (lowercase works). MkDocs uses !!! note (no blockquote). Mixing these up produces raw text instead of styled callouts.

Mistake 2: Forgetting the blank > line between paragraphs.

> [!WARNING]
> First paragraph.
> Second paragraph (this is still the first paragraph on GitHub).

Add a blank > line between paragraphs inside GitHub alerts:

> [!WARNING]
> First paragraph.
>
> Second paragraph (now correctly separated).

Mistake 3: Overusing callouts.

Five callouts on a 500-word page create visual noise. Use them sparingly for genuinely important information.

Try Callout Syntax in Our Editor

Our editor renders standard blockquotes but not the [!NOTE] alert extension, so the portable pattern below (a blockquote with a bold label) is what you will see in the preview and on any CommonMark renderer. Try different callout patterns below:

Frequently Asked Questions

Summary

Markdown callouts help you highlight notes, tips, warnings, and critical information with visual emphasis. GitHub's 5 alert types cover most documentation needs. Obsidian adds custom titles, 13 types, and collapsible behavior. MkDocs uses a completely different indentation-based syntax. Choose the right type based on urgency, limit usage to 2 to 4 per page, and check your target platform's support before writing. Use the editor to preview your content or visit the markdown cheat sheet for all syntax options.

Written by the Markdown Editor Online team. Last updated September 2026.