How to Use Obsidian Callouts for Structured Content: Syntax, Nesting, and Customization

Obsidian callouts are block-quote containers that use the >[!type] syntax to organize information with visual icons, customizable colors, and collapsible sections, supporting full markdown including tables, headings, and nested callouts.

Obsidian callouts provide a semantic way to highlight and structure information within your notes without breaking the markdown flow. According to the kepano/obsidian-skills repository, these containers are parsed as enhanced block quotes, allowing you to embed complex content while maintaining readability in source view. The reference documentation in skills/obsidian-markdown/references/CALLOUTS.md defines the complete syntax for creating everything from simple tips to multi-level FAQ hierarchies.

Understanding Obsidian Callout Syntax

Every Obsidian callout begins with a block-quote marker followed by a type declaration wrapped in square brackets with an exclamation point. The parser recognizes five distinct components that control the callout's appearance and behavior.

Component Breakdown

• Marker: The > character starts the block quote and must prefix every line of the callout content.
• Type: [!type] determines the visual style using built-in aliases like note, tip, warning, or faq. The type accepts custom identifiers for CSS targeting.
• Title: An optional custom title placed after the type overrides the default label.
• Foldable flag: Append - for collapsed or + for expanded state to make the callout collapsible.
• Content: Any valid markdown including nested callouts, provided each line maintains the > prefix.

> [!warning] Custom Title
> This content appears inside the warning callout.
> 
> > [!tip] Nested Tip
> > This is a callout inside a callout.

Embedding Structured Content Inside Callouts

Because callouts are parsed as block quotes, they accept the complete range of Obsidian markdown syntax. This makes them suitable for complex documentation that requires tables, headings, and actionable items within a single container.

Headings and Data Tables

You can organize callout content using standard markdown headings and pipe tables to present structured data:

> [!note] Project Overview
> 
> ## Objectives

> - Deliver MVP by Q2
> - Gather user feedback
> 
> ## Success Metrics

> | Metric          | Target |
> |-----------------|--------|
> | Active Users    | 5,000  |
> | Retention (30d) | 40%    |

Task Lists and Embeds

Callouts support task lists for actionable workflows and file embeds for referencing external content:

> [!checklist] Release Preparation
> - [ ] Update documentation
> - [ ] Run integration tests
> 
> ![[release-notes.pdf]]

Creating Foldable and Nested Callouts

Obsidian callouts support collapsible sections through foldable flags and hierarchical nesting through additional quote levels.

Collapsible Sections

Add - immediately after the type to collapse the callout by default, or + to expand it:

> [!faq]- Frequently Asked Questions
> Content is hidden until clicked.

Nested Callout Hierarchies

Create nested structures by adding an extra > for each level of depth. This pattern is documented in skills/obsidian-markdown/SKILL.md for building complex FAQ sections:

> [!faq]- Frequently Asked Questions
> > [!question] How do I install the plugin?
> > Run `npm install` inside the vault’s plugins folder.
> 
> > [!question] Where are the settings stored?
> > In `/.obsidian/plugins/<plugin>/settings.json`.

Custom Callout Types with CSS

When built-in types like note or warning are insufficient, you can define custom callouts using CSS snippets. The selector targets the data-callout attribute, allowing you to specify custom colors and icons.

In skills/obsidian-markdown/references/CALLOUTS.md, the following CSS pattern is shown for creating an "idea" callout:

/* custom callout: "idea" */
.callout[data-callout="idea"] {
  --callout-color: 0, 150, 200;           /* teal */
  --callout-icon: lucide-lightbulb;       /* light-bulb icon */
}

Once defined in your CSS, use the custom type in markdown:

> [!idea] New Feature Proposal
> > Implement a drag-and-drop editor for callouts.
> > 
> > | Component   | Owner   |
> > |------------|---------|
> > | UI Design  | Alice   |
> > | Backend API| Bob     |

Practical Workflow Examples

The following patterns from the kepano/obsidian-skills repository demonstrate production-ready callout usage for technical documentation:

Critical Issue Tracking:

> [!warning] Critical Issue
> > The API key is missing. The system cannot sync data.
> 
> > [!error] Resolution Steps
> > 1. Open **Settings → API**.
> > 2. Paste your key and click **Save**.
> > 3. Restart Obsidian.

Structured Project Summary:

> [!note] Project Overview
> 
> # Objectives

> - Deliver MVP by Q2
> - Gather user feedback
> 
> # Success Metrics

> | Metric          | Target |
> |-----------------|--------|
> | Active Users    | 5,000  |
> | Retention (30d) | 40%    |
> 
> > [!tip] Remember
> > Use the `[[Roadmap]]` note to keep the timeline up-to-date.

Summary

• Obsidian callouts use the >[!type] syntax to create semantic, color-coded containers within block quotes.
• Structured content including headings, tables, task lists, and nested callouts requires the > prefix on every line.
• Foldable flags (- or +) enable collapsible sections for cleaner note organization.
• Custom styling is achieved through CSS targeting .callout[data-callout="custom-type"] to define unique colors and icons.
• Source files defining these patterns are located in skills/obsidian-markdown/references/CALLOUTS.md and related documentation within the kepano/obsidian-skills repository.

Frequently Asked Questions

What markdown syntax triggers an Obsidian callout?

A callout is triggered by a block-quote marker (>) followed immediately by a type identifier in square brackets prefixed with an exclamation mark, such as > [!note]. This syntax is parsed according to the specifications in skills/obsidian-markdown/references/CALLOUTS.md.

How do I collapse an Obsidian callout by default?

Append a minus sign (-) immediately after the callout type and before the optional title, like > [!warning]- Collapsed Title. Use a plus sign (+) instead if you want the callout expanded by default but still collapsible.

Can I use tables and headings inside Obsidian callouts?

Yes. Because callouts are extended block quotes, they support any valid markdown including pipe tables (|), ATX headings (#), task lists (- [ ]), and embeds (![[filename]]). Each line of the embedded content must start with the block-quote marker >.

Where are Obsidian callout types defined?

Built-in callout types and their aliases (such as tip/hint or warning/caution) are documented in skills/obsidian-markdown/references/CALLOUTS.md within the kepano/obsidian-skills repository. Custom types require CSS definitions targeting the data-callout attribute in your Obsidian theme or snippets folder.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}