Type > [!NOTE] into a Markdown file and on GitHub you get a styled, icon-prefixed callout box. Paste that exact same text into a plain CommonMark renderer, a Jekyll site with no plugin, or an old-school static blog, and you get an ordinary blockquote with the literal text [!NOTE] sitting inside it. This trips people up constantly, because GitHub’s alert syntax is popular enough — and looks native enough — that it’s easy to assume it’s part of Markdown itself. It isn’t. It’s a GitHub- and GitLab-specific extension, and it’s just one of at least three unrelated callout syntaxes in active use depending on which platform or static site generator you’re targeting.

This guide covers what each syntax actually looks like, which platforms understand it natively, which need a plugin or config change, and — the part most syntax tutorials skip — what happens when you paste one platform’s syntax into a renderer that doesn’t understand it. If you want the full syntax reference and platform-by-platform examples first, our complete guide to admonitions and callouts and our narrower guide to warning boxes and alerts cover that ground; this post assumes you already know the basic syntax and focuses on where it actually renders. And if you just want to generate correctly-formatted callout syntax for your specific target platform without memorizing four different formats, our new Markdown Callout Generator does that.

GitHub and GitLab Alerts: Native, But Not CommonMark

GitHub’s alert syntax — a blockquote whose first line is one of five fixed keywords in brackets — is the one most people encounter first:

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

> [!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 attention to avoid problems.

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

Those exact five types — no more, no fewer — are the only ones GitHub’s renderer recognizes. Typing > [!DANGER] or > [!INFO] doesn’t error, it just falls back to being an ordinary blockquote with literal bracket text, because those aren’t in GitHub’s fixed vocabulary. GitLab adopted the identical syntax and the same five types, so anything written for one generally displays correctly on the other.

The important gotcha: this is a renderer-level feature, not a Markdown-spec feature. It works in READMEs, issues, PRs, wikis, and discussions on github.com and gitlab.com specifically, because those two platforms’ own Markdown renderers added special-case handling for the [!KEYWORD] pattern inside a blockquote. Take that same text to a plain CommonMark or GFM-spec-only renderer, a Jekyll/kramdown site with no custom handling, an email client, or a PDF exporter, and you get a plain blockquote containing the literal string [!NOTE] — no styling, no icon, no color. It’s still readable, just not what you intended.

Obsidian Callouts: A Similar Look, a Different (Larger) Vocabulary

Obsidian’s callout syntax is close enough to GitHub’s to cause real confusion, but it’s a separate implementation with its own, much larger type vocabulary and an extra feature GitHub’s alerts don’t have at all:

> [!note] Project Setup
> Follow these steps to configure your environment.

> [!warning] Version Compatibility
> This plugin requires Obsidian 0.15.0 or higher.

> [!tip]- Collapsible Tip
> The minus sign after the type makes this foldable, closed by default.
> A plus sign instead makes it foldable, but open by default.

Obsidian recognizes over a dozen built-in types (note, abstract/summary, info, todo, tip/hint, success/check, question, warning/caution, failure/fail, danger/error, bug, example, quote), several of which are simply aliases for each other, plus a fold indicator (-/+ right after the closing bracket) that GitHub’s syntax has no equivalent for at all. Obsidian is also case-insensitive on the type keyword and lets you supply a custom title after it — [!warning] Version Compatibility — where GitHub’s alerts always use the fixed keyword itself as the visible title with no override.

Because the outer shape (> [!type]) looks so similar to GitHub’s, it’s easy to assume the two are interchangeable. They’re not: paste [!tip]- into GitHub and you get a plain blockquote reading “[!tip]- Collapsible Tip” with no folding behavior, because GitHub’s renderer only pattern-matches its own five fixed keywords and has no concept of the fold suffix. Paste [!IMPORTANT] into Obsidian and it renders as a plain, unstyled callout box with no icon, because important isn’t one of Obsidian’s built-in types (Obsidian falls back to a generic default box rather than an ordinary blockquote, but it’s still not the styled result you’d get on GitHub).

MkDocs: A Real Extension, Config Required, Indentation-Sensitive

MkDocs (via Python-Markdown’s admonition extension, or the more capable pymdownx.details for foldable versions) uses a completely different syntax shape — no blockquote > at all:

!!! note "Configuration Requirements"
    This feature requires Python 3.8+ and the following dependencies.

??? tip "Click to expand"
    Using `???` instead of `!!!` makes the block collapsible, closed by default.
    `???+` makes it collapsible but open by default.

Three things make this meaningfully different from the blockquote-based syntaxes above. First, it does nothing at all unless you’ve explicitly enabled it — add admonition (and pymdownx.details if you want the foldable ??? variant) under markdown_extensions: in mkdocs.yml. Without that config line, !!! note renders as a literal paragraph starting with three exclamation marks; there’s no fallback styling of any kind. Second, the content that belongs inside the block must be indented four spaces under the !!!/??? line — get the indentation wrong and Python-Markdown simply doesn’t associate that paragraph with the admonition, silently dropping it back to being a regular, un-boxed paragraph directly below an empty admonition. Third, the type vocabulary is open-ended rather than fixed: !!! note, !!! danger, !!! example, or any custom type name you’ve styled via CSS all work, since the extension doesn’t validate against a fixed keyword list the way GitHub’s alerts do.

None of GitHub’s, GitLab’s, or Obsidian’s blockquote-based syntax does anything special in MkDocs — a pasted > [!NOTE] block just renders as a plain, unstyled blockquote with visible bracket text, exactly like taking GitHub syntax to any other non-GitHub renderer.

Docusaurus: A Third Shape Entirely — Fenced Directives

Docusaurus (and MDX-based tooling more broadly) uses yet another format, based on triple-colon fenced directives rather than either blockquotes or indented blocks:

:::note
Useful information that users should know.
:::

:::tip[Optional Custom Title]
Helpful advice, with an optional title in square brackets.
:::

:::danger
Highlights dangerous actions or negative outcomes.
:::

Docusaurus supports five built-in types (note, tip, info, warning, danger) and works out of the box with no plugin config, since the directive syntax is built into Docusaurus’s MDX processing pipeline directly. The syntax shape — a fence of three colons opening and closing the block, with the type name immediately after the opening fence — has nothing in common with GitHub’s blockquote convention or MkDocs’s indented-content convention, so none of those interoperate with this one either. Paste :::note content into GitHub or a plain CommonMark renderer and you get exactly what it looks like: a paragraph starting and ending with three literal colons, no box, no styling.

Quick Reference

Platform Syntax shape Native or needs config Fold/collapse support
GitHub > [!TYPE] blockquote, 5 fixed types Native, no config No
GitLab > [!TYPE] blockquote, same 5 types as GitHub Native, no config No
Obsidian > [!type] blockquote, 12+ types, custom titles Native, no config Yes — [!type]- / [!type]+
MkDocs (Material or base theme) !!! type "Title", 4-space indented content Needs admonition extension enabled in mkdocs.yml Yes, with pymdownx.details — ???/???+
Docusaurus :::type … ::: fenced directive Native (built into MDX pipeline) No (use a separate <details> for that)
Sphinx / reStructuredText .. type:: directive (not Markdown at all) Native to RST No
Plain CommonMark / unconfigured static sites N/A None of the above render specially — all fall back to a plain blockquote or paragraph with literal syntax visible N/A

What Doesn’t Cross-Render, Concretely

The pattern across every combination above is the same: each platform’s callout syntax is invisible to every other platform’s renderer, and none of them error — they all degrade to plain, unstyled Markdown with the literal syntax characters left visible in the text. Concretely:

  • GitHub-alert syntax (> [!NOTE]) pasted into a MkDocs site does not become a styled admonition — MkDocs’s admonition extension has no idea what a [!NOTE] blockquote is, so it renders as an ordinary blockquote with visible bracket text.
  • MkDocs syntax (!!! note) pasted into GitHub does not become a callout — GitHub’s renderer only pattern-matches its own five bracketed keywords inside blockquotes, and !!! note isn’t even inside a blockquote to begin with, so it just renders as a plain paragraph starting with !!!.
  • Docusaurus’s :::note fences pasted anywhere else — GitHub, Obsidian, MkDocs, plain Jekyll — render as plain text with visible colons, since the triple-colon-fence convention is specific to Docusaurus’s MDX processing.
  • Obsidian’s extended type vocabulary ([!bug], [!question], [!abstract]) pasted into GitHub renders as an unstyled blockquote, since those types fall outside GitHub’s fixed five.

If you’re writing documentation that has to look right on more than one of these platforms — a README that also gets built into a MkDocs or Docusaurus site, for instance — plain HTML <div class="admonition"> markup (styled with your own CSS) is still the only genuinely universal fallback, at the cost of losing GitHub’s and Obsidian’s zero-config native styling. There’s no single syntax that renders correctly everywhere; you’re choosing per target platform, not writing once.

And if you’d rather generate the correct syntax for your target platform than memorize four different formats, try the Markdown Callout Generator.