Custom Callout Extension For Quarto

The {quarto-custom-callout} extension provides a YAML interface to configure a Quarto Callout with custom values such as its title, icon, icon symbol, color, appearance, and collapsibility.

[!IMPORTANT]

This extension supports Quarto HTML documents and RevealJS presentations. We hope to extend this to other formats in the future.

Installing

To install the {quarto-custom-callout} extension, follow these steps:

1. Open your terminal.
2. Navigate to your Quarto project directory.
3. Execute the following command:

quarto add coatless-quarto/custom-callout

This will install the extension under the _extensions subdirectory. If you're using version control, you will want to check in this directory.

Using

The custom-callout extension allows you to define custom callouts in your YAML front matter and then use them in your Quarto documents. Here's a quick overview of the available YAML options:

You can start using custom callouts in your Quarto project immediately after installation. First, define your custom callouts in the YAML front matter:

custom-callout:
  todo:
    icon-symbol: "📝"
    color: "pink"
  thumbs-up:
    title: "Great job!"
    icon-symbol: "fa-thumbs-up"
    color: "#008000"
filters:
- custom-callout

Then, use the custom callouts in your Quarto document like this:

::: todo
Remember to complete this section.
:::

::: test
This information is crucial for understanding the concept.
:::

::: {.thumbs-up title="That was a hard task!"}
You did a great job completing this task.
:::

The above example will render three custom callouts in your document: one with a pink border and a "📝" icon, an orange border and a "⚠️" icon, and a green border with a thumbs-up icon from FontAwesome.

Notes

The {quarto-custom-callout} extension uses Quarto's quarto.Callout custom AST Node to create custom Quarto Callouts.

Previously, there were two approaches to creating custom callouts. Both approaches rely on using a Div node. Specifically, we have:

1. Create custom CSS classes with the necessary styling and apply it to a Div node.
2. Use {quarto-custom-numbered-blocks} extension by Ute Hahn.

The latter approach is more user-friendly and allows for the creation of custom number blocks with a YAML interface. Further, it offers immense flexibility in terms of styling and customization compared to the quarto.Callout() custom AST Node used by {quarto-custom-callout}. For example, if you need grouped callouts, you can use the groups option in the {quarto-custom-numbered-blocks} extension to formulate joint counters and styles. It's a great extension to use if you need more than just custom callouts.