Quarto Callouts Cheatsheet

A visual guide to Quarto’s five callout types, appearance styles, and cross-references.

quarto
callouts
cheatsheet
Author

James Balamuta

Published

March 28, 2026

Quarto provides five built-in callout block types for highlighting content in your documents. Each type has a distinct color and icon, and you can control the visual style with three appearance variants. Callouts also support collapsing, custom titles, icon toggling, and cross-references. This post covers every option with visual diagrams and code snippets. For the full reference, see the Callout Blocks page in the Quarto documentation.

Complete Quarto Callouts cheatsheet (light mode).

Download the full cheatsheet

All diagrams in a single, printable SVG.

Light SVG Dark SVG

Complete Quarto Callouts cheatsheet (dark mode).

Download the full cheatsheet

All diagrams in a single, printable SVG.

Light SVG Dark SVG

Callout Types

Quarto includes five callout types: note, warning, important, tip, and caution. Each renders with its own color and icon.

Five styled callout cards stacked vertically showing note (indigo), warning (amber), important (rose), tip (emerald), and caution (orange), each with its icon, title, and class name.

The five callout types with their default colors and icons

Five styled callout cards stacked vertically showing note (indigo), warning (amber), important (rose), tip (emerald), and caution (orange), each with its icon, title, and class name.

The five callout types with their default colors and icons

The basic syntax wraps content in a fenced div with the callout class:

::: {.callout-note}
This is a note callout. Use it for supplementary information.
:::

You can also add a title with a heading inside the callout:

::: {.callout-tip}
## Pro Tip
Use callouts to draw attention to key information.
:::

Appearance Variants

Three appearance styles control how callouts look. The default style shows a colored header background with an icon. The simple style removes the header background but keeps the icon and adds a left accent border. The minimal style strips the icon as well, leaving only a left border.

Three callout cards showing the same note callout in default style with colored header and icon, simple style with left border and icon but no header background, and minimal style with left border only and no icon.

Three appearance variants: default, simple, and minimal

Three callout cards showing the same note callout in default style with colored header and icon, simple style with left border and icon but no header background, and minimal style with left border only and no icon.

Three appearance variants: default, simple, and minimal

Set the appearance per callout or globally in YAML:

::: {.callout-note appearance="simple"}
A simpler look with no header background.
:::
---
callout-appearance: minimal
---

Features

Callouts support collapsing (expanded or collapsed by default), custom titles (via a heading or the title attribute), and toggling the icon on or off.

Diagram showing expanded and collapsed callout states with chevron indicators, two methods for setting custom titles, a titleless callout, and icon on versus icon off comparison.

Collapsible states, custom titles, and icon visibility

Diagram showing expanded and collapsed callout states with chevron indicators, two methods for setting custom titles, a titleless callout, and icon on versus icon off comparison.

Collapsible states, custom titles, and icon visibility

Collapsible callouts use the collapse attribute. Set collapse="true" to start collapsed or collapse="false" to start expanded (both become toggleable). Omitting the attribute keeps the callout static.

::: {.callout-tip collapse="true"}
## Click to Expand
Hidden content revealed on click.
:::

Custom titles can be set two ways. Place a heading inside the callout, or use the title attribute directly:

::: {.callout-note title="Did You Know?"}
The title attribute works on any callout type.
:::

Icon visibility is controlled per callout or globally:

::: {.callout-note icon=false}
This callout has no icon.
:::
---
callout-icon: false
---

Cross-References

You can cross-reference callouts by giving them an ID with a type-specific prefix, then using @-syntax elsewhere in your document.

Five prefix cards showing nte- for note, tip- for tip, wrn- for warning, imp- for important, and cau- for caution, followed by a usage example demonstrating how to define a callout with an ID and reference it with @-syntax.

Cross-reference prefixes and @-syntax for all five callout types

Five prefix cards showing nte- for note, tip- for tip, wrn- for warning, imp- for important, and cau- for caution, followed by a usage example demonstrating how to define a callout with an ID and reference it with @-syntax.

Cross-reference prefixes and @-syntax for all five callout types

Define a callout with an ID, then reference it:

::: {#tip-example .callout-tip}
## Helpful Tip
This tip can be referenced elsewhere.
:::

As shown in @tip-example, callouts are powerful.

The reference renders as a numbered link (for example, “Tip 1”) that points back to the callout. The callout must have both an ID and a title for cross-references to work.

Custom Callouts

The five built-in types cover most use cases. If you need custom callout types with your own colors and icons for HTML output, the custom-callout Quarto extension provides that capability.

Diagram showing the custom-callout extension install command, YAML configuration with color, icon, title, collapse properties, and a rendered custom To Do callout with purple styling.

Custom callout extension showing YAML configuration and rendered output

Diagram showing the custom-callout extension install command, YAML configuration with color, icon, title, collapse properties, and a rendered custom To Do callout with purple styling.

Custom callout extension showing YAML configuration and rendered output

Quick Reference

The five callout types and their intended use.
Type Class Color Use Case
Note .callout-note Blue Supplementary information
Warning .callout-warning Amber Potential issues
Important .callout-important Rose Critical, must-read content
Tip .callout-tip Green Helpful advice
Caution .callout-caution Orange Proceed with care
Callout customization options.
Option Values Scope
appearance default, simple, minimal Attribute
callout-appearance default, simple, minimal YAML (global)
collapse true, false Attribute
icon true, false Attribute
callout-icon true, false YAML (global)
title Any text Attribute
Cross-reference prefixes for each callout type.
Type Cross-ref Prefix Example ID Reference Syntax
Note nte- #nte-myid @nte-myid
Tip tip- #tip-myid @tip-myid
Warning wrn- #wrn-myid @wrn-myid
Important imp- #imp-myid @imp-myid
Caution cau- #cau-myid @cau-myid
Format support for callout features.
Format Callouts Collapse Notes
HTML Yes Yes Full support with Bootstrap themes
PDF Yes No Styled via LaTeX
Typst Yes No Native Typst rendering
DOCX Yes No Styled as Word callout boxes
EPUB Yes No Basic styled rendering
Revealjs Yes No No collapse in presentations