Markdown Callout / Info Box Syntax Tutorial

Markdown itself doesn't have a native callout (info box) syntax. This feature is a platform-specific extension — every editor or documentation tool has implemented its own flavor. The good news is that most platforms keep the syntax straightforward, and they share a common foundation: they're all enhancements built on top of blockquotes.

This article organizes the callout syntax for every major platform so you can just copy the code for whichever tool you're using.

What Is a Callout, Exactly?

A callout is a colored, icon-decorated box inserted into a document to draw the reader's attention. Common types include:

Type	Purpose
Note	Supplementary details, side notes
Tip	Helpful suggestions, shortcuts
Warning	Risks to be aware of
Important	Critical information that must not be skipped
Caution	Operations that could cause data loss or errors
Info	General informational notices
Example	Code or usage examples

Different platforms support different numbers of types, but the core set is the same. Understanding the purpose makes the syntax easier to remember.

GitHub Alerts: The Simplest Way to Start

If you primarily write READMEs, Issues, or PR descriptions on GitHub, GitHub Alerts are all you need. The syntax is built on blockquotes — just add a [!TYPE] marker at the start of the quote:

> [!NOTE]
> This is a note.

> [!TIP]
> This is a useful tip.

> [!WARNING]
> This is a warning.

> [!IMPORTANT]
> This is important information.

> [!CAUTION]
> This indicates a dangerous action — proceed with care.

GitHub supports 5 types: NOTE, TIP, WARNING, IMPORTANT, and CAUTION. The type keyword is case-insensitive — [!note] and [!NOTE] produce the same result.

One thing worth noting: if your Markdown renderer doesn't support GitHub alerts, the content degrades gracefully into a regular blockquote with no special styling, but the text content is preserved. This is blockquote syntax's built-in fallback — Markdown's design philosophy favors graceful degradation.

Honestly, I've used GitHub alerts in READMEs across several projects — they're simple and easy to remember. But I did run into a rendering issue once when nesting > [!NOTE] inside a deeply nested list — the styling got a bit misaligned. My advice: use them between flat paragraphs, not deep inside nested structures.

Obsidian Callout: The Most Feature-Rich Syntax

Obsidian's callout syntax is nearly identical to GitHub Alerts — also using blockquote with [!TYPE] — but supports far more types:

> [!note]
> This is a note.

> [!info] Custom Title
> This callout has a custom title.

> [!warning]
> This is a warning.

> [!tip]
> This is a tip.

> [!example]
> This is an example.

> [!quote]
> This is a quote.

Obsidian supports 12 built-in types: note, abstract, info, todo, tip, success, question, warning, failure, danger, bug, example, and quote. Each comes with its own default color and icon.

Collapsible Callouts

Obsidian lets you make callouts collapsible by adding + or -:

> [!note]+ Click to collapse (expanded by default)
> This content is expanded by default and can be collapsed.

> [!note]- Click to expand (collapsed by default)
> This content is collapsed by default and must be clicked to reveal.

+ means expanded but collapsible, - means collapsed by default. This feature is incredibly useful when writing long documents — fold away supplementary details to keep the page clean.

Nested Callouts

Obsidian allows callouts to be nested within each other:

> [!note]
> Outer note
> > [!tip]
> > Inner tip

That said, nesting beyond two levels gets hard to read. I'd recommend limiting nesting to one level deep.

Custom Callout Types

Obsidian supports creating custom callout types via CSS. Add this to a CSS snippet:

.callout[data-callout="my-custom"] {
    --callout-color: 255, 100, 50;
    --callout-icon: lucide:flame;
}

Then use it in Markdown:

> [!my-custom] Custom Notice
> This is a custom callout type.

I ran into a gotcha when building a documentation site for a project: the data-callout value in CSS must match the [!type] in Markdown exactly, including case. I once wrote [!My-Custom] in the Markdown but used my-custom in the CSS — it wouldn't render correctly, and it took a while to track down the case mismatch.

MkDocs Material Admonition: The Standard for Doc Sites

MkDocs with the Material theme is a popular choice for technical documentation. Its admonitions use the !!! marker:

!!! note
    This is a note.

!!! warning "Custom Title"
    This is a warning with a custom title.

!!! tip ""
    This callout has no title — only the icon and content are shown.

A few syntax details to keep in mind:

!!! is followed by the type name (e.g., note, warning)
The type name can be followed by a quoted string for the title
Content must be indented by 4 spaces (this is the most common mistake for beginners)
An empty string title "" hides the title text

Collapsible Admonitions

Replace !!! with ??? to make admonitions collapsible:

??? tip "Click to expand"
    This admonition is collapsed by default.

???+ warning "Expanded by default"
    This admonition is expanded by default but can be collapsed.

??? collapses by default, ???+ expands by default but remains collapsible. You need to enable the pymdownx.details extension in mkdocs.yml.

Configuration

Add this to mkdocs.yml:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Docusaurus Admonition: Triple Colon Syntax

Docusaurus wraps content with three colons ::::

:::note
This is a note.
:::

:::tip[Custom Title]
This is a tip.
:::

:::warning
This is a warning.
:::

:::danger
This is a danger notice.
:::

Docusaurus supports 5 types: note, tip, info, warning, and danger. Custom titles use square brackets [title] instead of quotes — this detail differs from other platforms, so don't mix them up.

You can also use ::: and :::type as opening and closing markers:

:::note[My Title]
This is a content paragraph.

It can span multiple lines.
:::

MyST Markdown / Jupyter Book: Directive Syntax

MyST Markdown uses a directive syntax similar to code blocks:

```{note}
This is a note.

This is a warning.

This is a callout with a custom title.


It also supports collapsible content:

````markdown
```{note} Collapsible Note
:class: dropdown
This content is collapsed by default.


MyST is primarily used in Jupyter Book and academic documentation contexts. If you're writing research notes or technical books, this is likely the syntax you'll encounter.

## Quarto / Pandoc: Fence Div Syntax

Quarto (built on Pandoc) uses fence divs with `.callout-*` classes:

```markdown
::: {.callout-note}
This is a note.
:::

::: {.callout-tip}
This is a tip.
:::

::: {.callout-warning title="Custom Title"}
This is a warning with a custom title.
:::

Quarto supports 5 types: note, tip, warning, important, and caution. The syntax is a bit verbose, but it's consistent with Pandoc's fence div system.

Cross-Platform Compatibility Comparison

One table to see the differences across all platforms:

Feature	GitHub	Obsidian	MkDocs	Docusaurus	MyST	Quarto
Syntax	`> [!TYPE]`	`> [!TYPE]`	`!!! type`	`:::type`	```{type}	`::: {.callout-type}`
Built-in types	5	12+	Custom	5	Custom	5
Custom title	No	Yes	Yes	Yes	Yes	Yes
Collapsible	No	Yes	Yes	No	Yes	Yes
Nesting	Limited	Yes	Yes	Yes	Yes	Yes
Custom types	No	CSS	CSS	JSX	No	No
Fallback if unsupported	Plain blockquote	Plain blockquote	No render	No render	No render	No render

As the table shows, GitHub and Obsidian share the closest syntax — both use blockquote extensions. This means migrating Markdown between the two platforms has the lowest cost.

Which Syntax Should You Use?

Your choice depends on your use case:

GitHub READMEs only → GitHub Alerts — simple and sufficient
Obsidian note-taking → Obsidian Callouts — rich types, collapsible, nestable
Technical docs with MkDocs → MkDocs Admonitions — best with the Material theme
Docs with Docusaurus → Docusaurus Admonitions — triple colon syntax is clean and direct
Academic docs (Jupyter Book) → MyST directive syntax
Data science reports (Quarto) → Quarto Callouts

If your content needs to work across multiple platforms, my recommendation is to standardize on GitHub Alerts syntax (> [!TYPE]). It renders correctly on both GitHub and Obsidian, and on other platforms it at least degrades to a plain blockquote — your content won't be lost.

Frequently Asked Questions

Does the Markdown standard support callouts?

No. The CommonMark specification does not define callouts. All callout functionality is a platform-specific extension, and the syntax is not interchangeable between platforms.

Can I customize the colors and icons of GitHub Alerts?

No. GitHub only supports 5 preset types with fixed colors and icons. There is no customization option.

Can I add my own callout types in Obsidian?

Yes. Define callout[data-callout="type-name"] in a CSS snippet to create custom types with your own colors and icons.

Why does MkDocs admonition content require 4-space indentation?

This is a requirement of Python-Markdown's block plugin syntax. Content after !!! must be at the same indentation level, and 4 spaces is the standard. Incorrect indentation may cause the content to not be recognized as part of the admonition.

Can callout syntax from different platforms be mixed?

No. Each syntax only works on its own platform. If you write :::note in Obsidian, it will just appear as plain text. Similarly, !!! note won't be recognized on GitHub.