Markdown Callouts Guide

What are Callouts?

While basic markdown only provides simple blockquotes (>), GitHub introduced enhanced design features that allow writers to emphasize specific content and clearly convey intent to readers through callout functionality. This feature has been adopted by other markdown rendering tools like GitLab and Obsidian and is now widely used.

Difference from Basic Markdown Blockquotes

Basic blockquote syntax:

> This is a basic markdown blockquote.
> It only provides a simple gray vertical line and indentation.

Rendered result:

This is a basic markdown blockquote. It only provides a simple gray vertical line and indentation.

In contrast, callouts provide rich visual elements like colors, icons, and titles to clearly convey the nature of the content.

Basic Usage

Callouts use the following syntax:

> [!type]
> Callout content

[!tip] Case Sensitivity Rules Callout types are case-insensitive. [!NOTE], [!note], and [!Note] all work identically.

However, it's recommended to choose one consistent rule:

Lowercase ([!note]): Faster typing without Shift key
Uppercase ([!NOTE]): More visually prominent and formal

Recommendation: Use lowercase. With markdown linters (standardization tools), you can automatically convert all callouts to uppercase later if needed, so it's more efficient to use convenient lowercase during writing and convert with tools when necessary.

Examples

> [!note]
> This is a note callout.

> [!warning]
> This is a warning callout.

> [!tip] Custom Title
> You can add a custom title.

Markdown Platform Callout/Alert Support Comparison

Callout Type	GitHub	GitLab	Obsidian
NOTE	✅	✅	✅
TIP	✅	✅	✅
IMPORTANT	✅	✅	✅
WARNING	✅	✅	✅
CAUTION	✅	✅	✅
info	❌	❌	✅
todo	❌	❌	✅
abstract	❌	❌	✅
summary	❌	❌	✅
tldr	❌	❌	✅
hint	❌	❌	✅
success	❌	❌	✅
check	❌	❌	✅
done	❌	❌	✅
question	❌	❌	✅
help	❌	❌	✅
faq	❌	❌	✅
attention	❌	❌	✅
failure	❌	❌	✅
fail	❌	❌	✅
missing	❌	❌	✅
danger	❌	❌	✅
error	❌	❌	✅
bug	❌	❌	✅
example	❌	❌	✅
quote	❌	❌	✅
cite	❌	❌	✅

Recommendation - Simplicity is Productivity

While Obsidian offers 25 different callout types, we strongly recommend using only the 5 common types.

Key reasons:

Reduced choice fatigue: No need to choose among 25 options - just remember 5
Focus on writing: Spend time on content, not callout selection
Maintain consistency: Build unified style across teams and projects
Ensure compatibility: Works identically across GitHub, GitLab, and other platforms
Minimize cognitive load: Readers only need to understand 5 familiar types

Recommended 5 types: NOTE (information), TIP (tips), IMPORTANT (important), WARNING (warning), CAUTION (caution)

These 5 types can effectively express 99% of situations. More choices aren't always better.

Basic Information Callouts

Used to display basic information or notes that users should be aware of.

Note

GitHub	GitLab	Obsidian
✅	✅	✅

Note

Displays basic information or notes.

Info

GitHub	GitLab	Obsidian
❌	❌	✅

Info

Displays informational content or guidance.

Todo

GitHub	GitLab	Obsidian
❌	❌	✅

Todo

Displays to-do items or task lists.

Help and Suggestion Callouts

Used to provide helpful tips or emphasize important information for users.

Tip

GitHub	GitLab	Obsidian
✅	✅	✅

Tip

Displays useful tips or suggestions.

Hint

GitHub	GitLab	Obsidian
❌	❌	✅

Hint

Used to provide hints or clues.

Important

GitHub	GitLab	Obsidian
✅	✅	✅

Important

Emphasizes important information or key content.

Question and Help Callouts

Used to address user questions or provide assistance.

Question

GitHub	GitLab	Obsidian
❌	❌	✅

Question

Displays questions or inquiries.

Help

GitHub	GitLab	Obsidian
❌	❌	✅

Help

Provides help information or usage instructions.

FAQ

GitHub	GitLab	Obsidian
❌	❌	✅

Faq

Displays frequently asked questions and answers.

Warning and Caution Callouts

Used to convey warnings or cautionary information to users.

Warning

GitHub	GitLab	Obsidian
✅	✅	✅

Warning

Warns about matters requiring attention.

Caution

GitHub	GitLab	Obsidian
✅	✅	✅

Caution

Alerts about content requiring caution or risk factors.

Attention

GitHub	GitLab	Obsidian
❌	❌	✅

Attention

Emphasizes content requiring special attention.

Success and Completion Callouts

Used to display successful results or completed tasks.

Success

GitHub	GitLab	Obsidian
❌	❌	✅

Success

Displays successful results or positive status.

Check

GitHub	GitLab	Obsidian
❌	❌	✅

Check

Displays confirmed content or verified information.

Done

GitHub	GitLab	Obsidian
❌	❌	✅

Done

Displays completed tasks or finished content.

Summary and Organization Callouts

Used to summarize content or provide concise key points.

Abstract

GitHub	GitLab	Obsidian
❌	❌	✅

Abstract

Provides an overview of a document or content.

Summary

GitHub	GitLab	Obsidian
❌	❌	✅

Summary

Summarizes and organizes key content.

TLDR

GitHub	GitLab	Obsidian
❌	❌	✅

Tldr

Too Long; Didn't Read - provides a brief summary of lengthy content.

Error and Problem Callouts

Used to display errors, failures, and issues.

Failure

GitHub	GitLab	Obsidian
❌	❌	✅

Failure

Displays failed results or problematic situations.

Fail

GitHub	GitLab	Obsidian
❌	❌	✅

Fail

Indicates failure situations or incorrect results.

Missing

GitHub	GitLab	Obsidian
❌	❌	✅

Missing

Displays missing content or incomplete information.

Danger

GitHub	GitLab	Obsidian
❌	❌	✅

Danger

Warns about dangerous situations or serious problems.

Error

GitHub	GitLab	Obsidian
❌	❌	✅

Error

Displays error situations or error messages.

Bug

GitHub	GitLab	Obsidian
❌	❌	✅

Bug

Used to report bugs or software defects.

Example and Citation Callouts

Used to show examples or cite content from other sources.

Example

GitHub	GitLab	Obsidian
❌	❌	✅

Example

Provides specific examples or sample code.

Quote

GitHub	GitLab	Obsidian
❌	❌	✅

Quote

Displays quotes from other sources or famous sayings.

Cite

GitHub	GitLab	Obsidian
❌	❌	✅

Cite

Used to specify references or sources.

Advanced Features

Adding Titles (Supported by All Platforms)

GitHub	GitLab	Obsidian
✅	✅	✅

Custom Title

You can add a title after the callout type.

Folding/Expanding Feature (Obsidian Only)

GitHub	GitLab	Obsidian
❌	❌	✅

Syntax:

> [!info]- Collapsed by Default
> Using the minus (-) symbol displays the callout collapsed by default.

> [!info]+ Expanded by Default
> Using the plus (+) symbol displays the callout expanded by default.

Rendered result:

Collapsed by Default

Using the minus (-) symbol displays the callout collapsed by default.

Expanded by Default

Using the plus (+) symbol displays the callout expanded by default.

Nested Callouts (Obsidian Only)

GitHub	GitLab	Obsidian
❌	❌	✅

Syntax:

> [!warning] Outer Callout
> This is the outer callout.
> 
> > [!tip] Inner Callout
> > You can nest other callouts inside a callout.

Rendered result:

Outer Callout

This is the outer callout.

Inner Callout

You can nest other callouts inside a callout.