Obsidian callouts are underrated

Callouts are a way to make certain content stand out from the body text — warnings, tips, important notes, and similar asides that deserve visual emphasis. Two tools that support them are GitHub and Obsidian, though they use slightly different syntax.

GitHub Flavored Markdown Callouts

GitHub introduced callout support in late 2023. The syntax is a blockquote with a type tag on the first line:

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

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

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

> [!WARNING]
> Urgent information that needs immediate attention.

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

GitHub renders each of these with a distinct icon and color. Notes are blue. Tips are green. Important is purple. Warnings are yellow. Cautions are red.

The type tag must be the first line of the blockquote and must be spelled exactly as shown — it is case-insensitive, but the brackets and exclamation mark are required. Any additional lines in the blockquote become the callout body.

Obsidian Callouts

Obsidian uses a similar but more flexible syntax. The type tag goes in the first line of a blockquote:

> [!note]
> Basic note callout.

> [!warning] Custom title here
> You can override the default title with text after the type.

> [!tip]+ Expanded by default
> A `+` after the type makes the callout start expanded.

> [!info]- Collapsed by default
> A `-` after the type makes the callout start collapsed.

Obsidian supports more types than GitHub: note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote, and several aliases. It also allows nesting callouts inside each other.

When to Use Each Type

Choosing the right callout type makes the content clearer. Here is a rough guide:

Note / Info — Background context that is useful but not urgent. Use when you want to share something without implying the reader must act on it.

Tip — A better way to do something. Good for shortcuts, best practices, or alternatives the reader might not know about.

Important — Something that affects the outcome. If the reader skips this, the main task may not work correctly.

Warning — A side effect or gotcha. The action still works, but the reader should know about a consequence.

Caution / Danger — Potential for data loss, security issues, or irreversible actions. Reserve for situations where ignoring the note causes real harm.

GitHub vs Obsidian Compatibility

The two syntaxes are close but not identical. GitHub supports five types; Obsidian supports many more. The + and - fold syntax is Obsidian-only and GitHub will render it as plain blockquote text with a plus or minus in it.

If you are writing documentation that lives in a GitHub repository and is also viewed in Obsidian, stick to the five GitHub types and skip the fold syntax. Both tools will render them correctly.

If you are writing personal notes in Obsidian and do not care about GitHub rendering, the full Obsidian syntax is more expressive.

A Note on Custom Renderers

Neither GitHub nor Obsidian callout syntax is part of the CommonMark specification. Tools like Astro, Pandoc, or any standard Markdown parser will render callouts as plain blockquotes. If you want callouts on a custom site, you need a remark or rehype plugin — for example, remark-callout or rehype-callouts — to transform the blockquote nodes during build.

This means callouts are best treated as a documentation and note-taking tool, not as a content format you rely on in production pipelines without a compatible parser.