Skip to content

Latest commit

 

History

History
97 lines (72 loc) · 3.86 KB

README.md

File metadata and controls

97 lines (72 loc) · 3.86 KB
Raw

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 is designed for Quarto HTML documents. 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:

Option Description Default Possible Values Example
title Default title for the callout Callout name Any string title: "Important Note"
icon Display an icon false true, false icon: true
icon-symbol Custom symbol or text for the icon None Any string, unicode, or FontAwesome class icon-symbol: "📝"
color Color for the callout's left border and background None Any valid CSS color name or hex color: "#FFA500"
appearance Callout appearance "default" "default", "simple", "minimal" appearance: "simple"
collapse Make the callout collapsible false true, false collapse: true

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.