Callout Blocks

Callouts are an excellent way to draw extra attention to certain concepts, or to more clearly indicate that certain content is supplemental or applicable to only some scenarios.

Callout Types

There are five different types of callouts available.

  • note
  • tip
  • important
  • caution
  • warning

The color and icon will be different depending upon the type that you select. Here are what the various types look like in HTML output:

Note

Note that there are five types of callouts, including: note, tip, warning, caution, and important.

Tip With Caption

This is an example of a callout with a caption.

This is Important

Danger, callouts will really improve your writing.

Warning

Callouts provide a simple way to attract attention, for example, to this warning.

This is an example of a ‘collapsed’ caution callout that can be expanded by the user. You can use collapse="true" to collapse it by default or collapse="false" to make a collapsible callout that is expanded by default.

Markdown Syntax

Create callouts in markdown using the following syntax (note that the first markdown heading used within the callout is used as the callout heading):

:::{.callout-note}
Note that there are five types of callouts, including:
`note`, `tip`, `warning`, `caution`, and `important`.
:::

:::{.callout-tip}
## Tip With Caption

This is an example of a callout with a caption.
:::

:::{.callout-caution collapse="true"}
## Expand To Learn About Collapse

This is an example of a 'folded' caution callout that can be expanded by the user. You can use `collapse="true"` to collapse it by default or `collapse="false"` to make a collapsible callout that is expanded by default.
:::

Customizing Appearance

Collapse

You can create ‘folded’ callouts that can be expanded by the user by settings the collapse attribute on the callout. If you set collapse=true, the callout will be expandable, but will be collapsed by default. If you set collapse=false, the callout will be expanded, but will be expanded by default.

Appearance

Callouts have 3 different looks you can use.

default The default appearance with colored header and an icon.
simple A lighter weight appearance that doesn’t include a colored header background.
minimal A minimal treatment that applies borders to the callout, but doesn’t include a header background color or icon.

You can set the callout appearance either globally in the document (or project yaml):

callout-appearance: simple

or by setting the type attribute on the callout. For example

::: {.callout-note appearance="simple"}

## Pay Attention

Using callouts is an effective way to highlight content that your reader give special consideration or attention.

:::

which appears as:

Pay Attention

Using callouts is an effect way to highlight content that your reader give special consideration or attention.

Icons

In addition to controlling the appearance of the callout, you can also choose to directly suppress the icon but either setting the global option in your document (or project) yaml:

callout-icon: false;

or by setting an attribute directly on the callout:

::: {.callout-note icon=false}

## Pay Attention

Using callouts is an effective way to highlight content that your reader give special consideration or attention.

:::

Which will appear as:

Pay Attention

Using callouts is an effective way to highlight content that your reader give special consideration or attention.

Format Support

The following formats render callouts as illustrated above:

  • HTML
  • PDF
  • MS Word
  • EPUB

Note that callout rendering for HTML is not available when you disable the standard HTML theme (e.g. if you specify the theme: none option).

When the target format doesn’t support callouts, they are rendered as a simple blockquote with the caption in bold.