<!--
  canonical-url: https://www.avonture.be/blog/quarto-callout-blocks
  published:     2024-04-13
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

# Quarto Callout Blocks

> Discover the Quarto Callout Block syntax for creating attention-grabbing admonitions (Tips, Warnings, Cautions) in your reports. Includes a handy VSCode snippet.

---
![Quarto Callout Blocks](/img/v2/quarto.webp)

**TL;DR**

This article shows Quarto's callout-block syntax (`:::{.callout-caution}`, `:::{.callout-tip}`, etc.) for highlighted admonitions in PDF, HTML, and revealJS output — Quarto's equivalent of Docusaurus's `<AlertBox>` — and provides a VSCode snippet that interactively prompts for the callout type, title, and body so you never need to remember the exact syntax.

A callout (called *admonition* by [Docusaurus](https://docusaurus.io/docs/markdown-features/admonitions)) is a special syntax used to highlight a paragraph, f.i. a *Pay attention to...* or *Tip: Did you know that...* box. *On the Docusaurus side, I've covered that syntax in [Some tips and tricks when written articles for Docusaurus](/blog/docusaurus-articles-tips).*

On this blog powered by Docusaurus, the syntax for *admonition* is

```markdown
<AlertBox variant="caution" title="Pay attention to...">
Never give your bank card code to a stranger.

</AlertBox>
```

and this is rendered like

> **Pay attention to...:**
>
> Never give your bank card code to a stranger.

And now a nice tip:

> **Did you know that...:**
>
> By going to bed earlier, you'll get better quality sleep.

Quarto implements this a little differently, so let's have a look...

> **Docker image with Quarto:**
>
> If you don't have yet a Docker image with Quarto, read this article [Running Quarto Markdown in Docker](/blog/docker-quarto).

## Syntax

Unfortunately, the syntax is not part of the standard Markdown language, so every tool actually has its own.

For Quarto, the syntax is:

```markdown
:::{.callout-caution}
## Pay attention to...
Never give your bank card code to a stranger.
:::
```

And, that paragraph is converted like this in PDF:

![Callout Caution in PDF](./images/caution-pdf.webp)

The Quarto syntax for a tip is:

```markdown
:::{.callout-tip}
## Did you know that...
By going to bed earlier, you'll get better quality sleep.
:::
```

![Callout Tip in PDF](./images/tip-pdf.webp)

Callouts are supported in PDF, HTML, revealJS and other formats.

Get in-depth syntax on the [official documentation](https://quarto.org/docs/authoring/callouts.html).

## VSCode snippet

If you're a VSCode user, don't make an effort to remember the correct syntax but use the *Snippet* feature of VSCode.

Press `CTRL`-`SHIFT`-`P` to get access to the **Command Palette**.

Start to type `Configure User Snippets`, validate and select `markdown.json` since our snippets should be available only when writing Markdown content.

![Creating a snippet](./images/create-snippets.webp)

If this is your first snippet, the JSON file will be empty. Copy/paste the text below. Otherwise, just copy the `callout` node and paste it in your file to the correct location.

**markdown.json**

```json
{
    "callout": {
        "prefix": "quarto-callout",
        "body": [
            ":::{.callout-${1|note,tip,warning,caution,important|}}",
            "## ${2:title}",
            "${3:body}",
            ":::"
        ],
        "description": "Add a callout paragraph to your markdown file"
    }
}
```

Save and close the `markdown.json` file and go back to any markdown file (or create a new one).

Now, by typing `quarto` and by pressing `CTRL`-`space`, VSCode will show the list of possibilities for that word and you'll retrieve your snippet. Select it and press `Enter` to validate.

![Call the snippet](./images/call-snippets.webp)

And, as you can see on the image below, VSCode will ask you three things:

1. First the type of callout and you'll have a list of possible values; easy no?
2. Then, after having pressed the `tab` key, you'll be prompted to type a title and, finally,
3. The body of your paragraph.

![Using the snippet](./images/using-snippet.webp)

VSCode will show you the snippet interactively and you can then, easily, create it without having to remember the correct syntax.

```markdown
:::{.callout-caution}
## Pay attention to...
Never give your bank card code to a stranger.
:::
```
