Markdown alerts and callouts

To write a note or warning box in Markdown on GitHub, start a blockquote with an alert marker such as > [!NOTE] on the first line and put the message on the following > lines. GitHub supports five types: NOTE, TIP, IMPORTANT, WARNING and CAUTION. Alerts are not part of CommonMark, and other tools use different syntax: Obsidian has callouts, MkDocs has !!! admonitions and Docusaurus has :::note blocks. Where none of these is supported, a plain blockquote with a bold label is the portable fallback.

Markdown alerts and callouts reference

Key facts

• GitHub alerts are blockquotes whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION].
• Alerts are an extension. They are not in CommonMark or the GFM spec, and other renderers show the marker as plain text inside a blockquote.
• GitHub's docs say alerts cannot be nested within other elements and recommend using no more than one or two per article.
• GitLab added alerts in GitLab 17.10 with the same five types and supports a custom title after the marker.
• Obsidian callouts use the same > [!type] shape, with many more types, custom titles and folding with + or -.
• MkDocs (Material) and Docusaurus use their own block syntax, !!! note and :::note, which is not blockquote based.

GitHub alerts syntax

GitHub calls this feature alerts, and its documentation notes they are also known as callouts or admonitions. Each alert is a normal blockquote. The first line contains only the type marker in square brackets with an exclamation mark, and every following line of the alert starts with >.

A GitHub note

Markdown

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

Rendered output

HTML output

<div class="markdown-alert markdown-alert-note">
<p class="markdown-alert-title">Note</p>
<p>Useful information that users should know, even when skimming content.</p>
</div>

The HTML output is simplified. GitHub adds an icon and its own styling, and the exact markup may change.

GitHub documents exactly five alert types. The descriptions below are GitHub's own guidance on when to use each one.

A multi-line warning

Markdown

> [!WARNING]
> Back up your notes before upgrading.
>
> The upgrade rewrites the settings file.

Rendered output

HTML output

<div class="markdown-alert markdown-alert-warning">
<p class="markdown-alert-title">Warning</p>
<p>Back up your notes before upgrading.</p>
<p>The upgrade rewrites the settings file.</p>
</div>

GitHub's docs show the types in uppercase and do not document a custom title or any type beyond these five. An unknown marker such as [!INFO] is not listed, so expect it to display as an ordinary blockquote. Alerts cannot be nested inside other elements such as lists.

GitLab alerts

GitLab Flavored Markdown added alerts in GitLab 17.10. It uses the same blockquote shape and the same five types, written in lowercase in GitLab's docs: note, tip, important, caution and warning. Unlike GitHub, GitLab documents a custom title: any text on the same line as the marker replaces the default title.

GitLab alert with a custom title

Markdown

> [!warning] Data deletion
> This action cannot be undone.

Rendered output

HTML output

<div class="markdown-alert markdown-alert-warning">
<p class="markdown-alert-title">Data deletion</p>
<p>This action cannot be undone.</p>
</div>

HTML output is illustrative. Check the markup your GitLab version produces.

On self-managed GitLab instances older than 17.10, the marker displays as plain text inside a blockquote.

Obsidian callouts

Obsidian callouts use the same > [!type] first line, but add more features. Type identifiers are case-insensitive, text after the marker becomes the title, and a + or - right after the closing bracket makes the callout foldable. A plus sign expands it by default and a minus sign collapses it.

Foldable callout with a title

Markdown

> [!faq]- Why is my sync slow?
> Large attachments are uploaded one at a time.

Rendered output

HTML output

(Obsidian renders callouts in its own interface; there is no standard HTML output.)

The preview uses a collapsible element to approximate Obsidian's folded callout.

Obsidian supports these types, with aliases in parentheses: 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 and quote (cite). Unknown types fall back to note styling. Callouts can be nested by adding more > markers.

Because GitHub's five types all exist in Obsidian (as types or aliases), a GitHub alert also displays as a callout in Obsidian. The reverse is not true: titles, folding and extra types are ignored or shown as text on GitHub.

MkDocs and Docusaurus admonitions

Documentation site generators use their own block syntax instead of blockquotes. In MkDocs with the Material theme, the admonition extension provides !!! blocks. The type follows the markers, an optional quoted title follows the type, and the content is indented by four spaces.

!!! note "Before you start"
    Install Python 3.10 or later.

??? tip "Collapsed by default"
    Requires the pymdownx.details extension.

???+ warning
    Collapsible, but open by default.

??? creates a collapsible block and ???+ one that starts open; both need the pymdownx.details extension. Material for MkDocs lists the types note, abstract, info, tip, success, question, warning, failure, danger, bug, example and quote.

Docusaurus uses fenced directives with three colons. The built-in types are note, tip, info, warning and danger, and a title goes in square brackets after the type.

:::tip[Keyboard shortcut]

Press Ctrl+K to open search.

:::

Docusaurus recommends blank lines around the content so that Prettier does not reformat the directive into invalid syntax. Nested admonitions use more colons on the outer block.

Portable fallback for other renderers

In CommonMark and most renderers without an alerts extension, > [!NOTE] becomes a normal blockquote that starts with the literal text [!NOTE]. The content is still readable, but the label looks like a typo. If a document must look right everywhere, use a plain blockquote with a bold label.

Works in any Markdown renderer

Markdown

> **Note:** Settings sync requires an account.

> **Warning:** Deleting a vault cannot be undone.

Rendered output

HTML output

<blockquote>
<p><strong>Note:</strong> Settings sync requires an account.</p>
</blockquote>
<blockquote>
<p><strong>Warning:</strong> Deleting a vault cannot be undone.</p>
</blockquote>

Put a blank line between two fallback notes, as above. Without it, the two blockquotes merge into one. For more on the underlying syntax, see blockquotes.

Flavor differences

Each platform defines its own alert syntax. Only GitHub, GitLab and Obsidian share the > [!type] form, and even they differ in types, titles and folding.

When a file is read in several tools, GitHub's five uppercase types are the most widely recognized form of the [!type] syntax. See Markdown flavors for other differences.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific styles GitHub alert syntax: a blockquote whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] is shown as a colored alert, and the file itself is left unchanged so it still renders on GitHub. Obsidian callout titles and folding markers are Obsidian features; in other tools they appear as an ordinary alert or blockquote. Try it in the Markdific online editor.

Common mistakes and gotchas

• Putting text on the marker line on GitHub. GitHub documents the marker alone on the first line. Titles after the marker are a GitLab and Obsidian feature.
• Inventing types. GitHub supports only NOTE, TIP, IMPORTANT, WARNING and CAUTION. [!INFO] or [!DANGER] are not GitHub types.
• Missing the > on continuation lines. A line without > after a blank line ends the blockquote, and the rest falls outside the alert.
• Nesting alerts in lists. GitHub's docs say alerts cannot be nested within other elements.
• Mixing syntaxes. !!! note and :::note only work in MkDocs and Docusaurus. On GitHub they appear as plain text.
• Not indenting MkDocs content. Admonition content must be indented by four spaces or it is not included in the box.

Best practices

• Use alerts sparingly. GitHub recommends one or two per article and advises against placing them one after another.
• Pick the type by consequence: WARNING or CAUTION only when ignoring the text causes a problem.
• Keep alert text short. Long explanations belong in the main body.
• Use the syntax of the platform where the document is published, and preview it there.
• For portable documents, use a blockquote with a bold label such as **Note:**.

FAQ

How do I create a note or warning box in Markdown? On GitHub, start a blockquote with > [!NOTE] or > [!WARNING] on the first line and write the message on the following > lines. In other tools, use a blockquote with a bold label such as > **Note:**.

What alert types does GitHub support? Five: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION].

Can I add a custom title to a GitHub alert? GitHub's documentation does not describe a custom title. GitLab and Obsidian both support one by placing text after the marker, for example > [!warning] Data deletion.

Does GitLab support > [!NOTE] alerts? Yes, since GitLab 17.10. It supports note, tip, important, caution and warning, and allows a custom title on the marker line.

What is the difference between a callout and an admonition? They are different names for the same idea: a highlighted box for a note, tip or warning. Obsidian calls them callouts, MkDocs and Docusaurus call them admonitions, and GitHub calls them alerts. The syntax differs by tool.

How do I make a collapsible callout? In Obsidian, add - after the marker to collapse it by default or + to make it foldable but open, for example > [!tip]- Title. In MkDocs Material, use ??? or ???+. GitHub alerts cannot fold; use details and summary instead.

Why does [!NOTE] show as plain text? The renderer does not support alerts. CommonMark and many editors treat it as an ordinary blockquote. Use a bold label such as **Note:** for portable documents.

Sources and compatibility references

• GitHub Docs: Basic writing and formatting syntax (Alerts)
• GitHub Changelog: New Markdown extension, alerts (December 14, 2023)
• GitLab Docs: GitLab Flavored Markdown (Alerts)
• Obsidian Help: Callouts
• Material for MkDocs: Admonitions
• Docusaurus: Admonitions
• Visual Studio Code: Markdown and Visual Studio Code

Use these primary references for syntax rules. Renderer behavior can still vary by version and configuration, so preview important documents in their final destination.

To see how your Markdown renders while you write, open the file in Markdific, a Markdown viewer and editor for Mac, Windows and Linux.

Related pages

• Markdown documentation hub
• Blockquotes
• Collapsible sections
• Emphasis
• Markdown flavors
• Inline HTML
• Markdown cheat sheet