Custom callouts for quarto

Callouts are a fantastic quarto feature for highlighting part of the text.

This is a callout

This is the body of a callout

Callouts come in several flavours: tip, note, information, caution and warning, each with their own colour and icon.

But what if you want to use a different icon? One that is more appropriate for the purpose of the callout.

Andreas Haldel has one solution. Melissa van Bussel has a similar one. Both copy the css used to make a standard callout and modify it to make a new callout. My problem is that the markdown to create the callout is clunky.

For a normal callout, we can code it like this

::: callout-note
## header of note

Body of note
:::

Andrea’s solution requires something like this

:::{.goals}
::::{.goals-header}
Learning Goals
::::
::::{.goals-container}
* Know how to make your own callouts.
* Be able to mess with some SCSS/CSS styling.
::::
:::

I want to be able to use the original markdown.

The best solution would be to rewrite the lua filters that make the callout for quarto to accept new types of callout. I have not the foggiest idea how to do that, so I’m going to propose a much easier hack solution.

The question I’m asking myself is - do I really need caution and warning callouts? If I don’t, can I recycle the one of these into a custom callout?

The CSS that makes the callout is available on github (I am focusing on html callouts because I do all my work with callouts in html).

This is all the CSS specific to caution-flavoured callouts.

div.callout-caution {
  border-left-color: #fd7e14 !important;
}

div.callout-caution .callout-icon::before {
  background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAERlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAACshmLzAAACV0lEQVRYCdVWzWoUQRCuqp2ICBLJXgITZL1EfQDBW/bkzUMUD7klD+ATSHBEfAIfQO+iXsWDxJsHL96EHAwhgzlkg8nBg25XWb0zIb0zs9muYYWkoKeru+vn664fBqElyZNuyh167NXJ8Ut8McjbmEraKHkd7uAnAFku+VWdb3reSmRV8PKSLfZ0Gjn3a6Xlcq9YGb6tADjn+lUfTXtVmaZ1KwBIvFI11rRXlWlatwIAAv2asaa9mlB9wwygiDX26qaw1yYPzFXg2N1GgG0FMF8Oj+VIx7E/03lHx8UhvYyNZLN7BwSPgekXXLribw7w5/c8EF+DBK5idvDVYtEEwMeYefjjLAdEyQ3M9nfOkgnPTEkYU+sxMq0BxNR6jExrAI31H1rzvLEfRIdgcv1XEdj6QTQAS2wtstEALLG1yEZ3QhH6oDX7ExBSFEkFINXH98NTrme5IOaaA7kIfiu2L8A3qhH9zRbukdCqdsA98TdElyeMe5BI8Rs2xHRIsoTSSVFfCFCWGPn9XHb4cdobRIWABNf0add9jakDjQJpJ1bTXOJXnnRXHRf+dNL1ZV1MBRCXhMbaHqGI1JkKIL7+i8uffuP6wVQAzO7+qVEbF6NbS0LJureYcWXUUhH66nLR5rYmva+2tjRFtojkM2aD76HEGAD3tPtKM309FJg5j/K682ywcWJ3PASCcycH/22u+Bh7Aa0ehM2Fu4z0SAE81HF9RkB21c5bEn4Dzw+/qNOyXr3DCTQDMBOdhi4nAgiFDGCinIa2owCEChUwD8qzd03PG+qdW/4fDzjUMcE1ZpIAAAAASUVORK5CYII=');
}

div.callout-caution.callout-style-default .callout-title {
  background-color: #ffe5d0
}

The first sets the colour of the left border of a callout. The second sets the icon. And the third is supposed to set the background colour of the callout header, but doesn’t seem to do anything.

The default icon for a caution callout is a traffic cone. To change it to an icon I downloaded from fontawesome, I add this css. You can pick the colour when you download it, or edit the svg file to have any colour you choose.

div.callout-caution .callout-icon::before {
  background-image: url("magnifying-glass-solid.svg") !important;
}

It is important to add !important so that this CSS is used instead of the default.

Magnifying glass

This callout would have an orange header and sidebar were it not the changes made below.

The css can directly into the document (in which case you should set \| echo: false to stop it printing). But is probably best in a css or scss file which can be called from the yaml using the css and theme keys respectively.

But what if you don’t like the colour. The obvious thing is to change the CSS for the colours.

```{css}
div.callout-caution {
  border-left-color: #0d7e14 !important;
}


div.callout-caution.callout-style-default .callout-title {
  background-color: #0fe5d0 !important;
}
```

Alas, this only changes the sidebar colour. I don’t understand why.

Fortunately, there is another way. We can make a scss file and change the callout colour there. We can also add the icon.

The lines about scss:defaults and scss:rules are important!

/*-- scss:defaults --*/
$callout-color-caution: #0a0ffb;

/*-- scss:rules --*/

div.callout-caution .callout-icon::before {
  background-image: url('magnifying-glass-solid.svg') !important;
}

We can use this scss file by adding it to the yaml

---
theme: callout.scss
---

Magnifying glass

A callout with our choice of colour and icon.

One challenge is making sure that the icon is in the correct directory. A solution to this is to encode the svg file and add it as data:image as in the original css. We can use utils::URLencode to encode the file (hint use single quotes or escape the double quotes in the file.)

logo <- '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="#0a0ffb" d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352a144 144 0 1 0 0-288 144 144 0 1 0 0 288z"/></svg>'
URLencode(logo)

[1] "%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20viewBox=%220%200%20512%20512%22%3E%3C!--!Font%20Awesome%20Free%206.6.0%20by%20@fontawesome%20-%20https://fontawesome.com%20License%20-%20https://fontawesome.com/license/free%20Copyright%202024%20Fonticons,%20Inc.--%3E%3Cpath%20fill=%22#0a0ffb%22%20d=%22M416%20208c0%2045.9-14.9%2088.3-40%20122.7L502.6%20457.4c12.5%2012.5%2012.5%2032.8%200%2045.3s-32.8%2012.5-45.3%200L330.7%20376c-34.4%2025.2-76.8%2040-122.7%2040C93.1%20416%200%20322.9%200%20208S93.1%200%20208%200S416%2093.1%20416%20208zM208%20352a144%20144%200%201%200%200-288%20144%20144%200%201%200%200%20288z%22/%3E%3C/svg%3E"

So now my scss file looks like

/*-- scss:defaults --*/
$callout-color-caution: #0a0ffb;

/*-- scss:rules --*/
div.callout-caution .callout-icon::before {
   background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'%3E%3C!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--%3E%3Cpath fill='%230a0ffb' d='M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352a144 144 0 1 0 0-288 144 144 0 1 0 0 288z'/%3E%3C/svg%3E") !important;
}

--- title: "Custom callouts for quarto" author: "Richard J. Telford" date: "2024-08-12" categories: [quarto] --- Callouts are a fantastic quarto feature for highlighting part of the text. ::: callout-note ## This is a callout This is the body of a callout ::: Callouts come in several flavours: tip, note, information, caution and warning, each with their own colour and icon. But what if you want to use a different icon? One that is more appropriate for the purpose of the callout. Andreas Haldel has [one solution](https://www.andreashandel.com/posts/2023-06-13-custom-callouts-quarto/). Melissa van Bussel has a [similar one](https://www.youtube.com/watch?v=DDQO_3R-q74&t=4s). Both copy the css used to make a standard callout and modify it to make a new callout. My problem is that the markdown to create the callout is clunky. For a normal callout, we can code it like this ```{markdown} ::: callout-note ## header of note Body of note ::: ``` Andrea's solution requires something like this ```{markdown} :::{.goals} ::::{.goals-header} Learning Goals :::: ::::{.goals-container} * Know how to make your own callouts. * Be able to mess with some SCSS/CSS styling. :::: ::: ``` I want to be able to use the original markdown. The best solution would be to rewrite the lua filters that make the callout for quarto to accept new types of callout. I have not the foggiest idea how to do that, so I'm going to propose a much easier hack solution. The question I'm asking myself is - do I really need caution and warning callouts? If I don't, can I recycle the one of these into a custom callout? The CSS that makes the callout is available on [github](https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/html/styles-callout.html) (I am focusing on html callouts because I do all my work with callouts in html). This is all the CSS specific to caution-flavoured callouts. ```{markdown} div.callout-caution { border-left-color: #fd7e14 !important; } div.callout-caution .callout-icon::before { background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAERlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAACshmLzAAACV0lEQVRYCdVWzWoUQRCuqp2ICBLJXgITZL1EfQDBW/bkzUMUD7klD+ATSHBEfAIfQO+iXsWDxJsHL96EHAwhgzlkg8nBg25XWb0zIb0zs9muYYWkoKeru+vn664fBqElyZNuyh167NXJ8Ut8McjbmEraKHkd7uAnAFku+VWdb3reSmRV8PKSLfZ0Gjn3a6Xlcq9YGb6tADjn+lUfTXtVmaZ1KwBIvFI11rRXlWlatwIAAv2asaa9mlB9wwygiDX26qaw1yYPzFXg2N1GgG0FMF8Oj+VIx7E/03lHx8UhvYyNZLN7BwSPgekXXLribw7w5/c8EF+DBK5idvDVYtEEwMeYefjjLAdEyQ3M9nfOkgnPTEkYU+sxMq0BxNR6jExrAI31H1rzvLEfRIdgcv1XEdj6QTQAS2wtstEALLG1yEZ3QhH6oDX7ExBSFEkFINXH98NTrme5IOaaA7kIfiu2L8A3qhH9zRbukdCqdsA98TdElyeMe5BI8Rs2xHRIsoTSSVFfCFCWGPn9XHb4cdobRIWABNf0add9jakDjQJpJ1bTXOJXnnRXHRf+dNL1ZV1MBRCXhMbaHqGI1JkKIL7+i8uffuP6wVQAzO7+qVEbF6NbS0LJureYcWXUUhH66nLR5rYmva+2tjRFtojkM2aD76HEGAD3tPtKM309FJg5j/K682ywcWJ3PASCcycH/22u+Bh7Aa0ehM2Fu4z0SAE81HF9RkB21c5bEn4Dzw+/qNOyXr3DCTQDMBOdhi4nAgiFDGCinIa2owCEChUwD8qzd03PG+qdW/4fDzjUMcE1ZpIAAAAASUVORK5CYII='); } div.callout-caution.callout-style-default .callout-title { background-color: #ffe5d0 } ``` The first sets the colour of the left border of a callout. The second sets the icon. And the third is supposed to set the background colour of the callout header, but doesn't seem to do anything. The default icon for a caution callout is a traffic cone. To change it to an icon I downloaded from [fontawesome](https://fontawesome.com/icons/), I add this css. You can pick the colour when you download it, or edit the svg file to have any colour you choose. ```{css} div.callout-caution .callout-icon::before { background-image: url("magnifying-glass-solid.svg") !important; } ``` It is important to add `!important` so that this CSS is used instead of the default. ::: callout-caution ## Magnifying glass This callout would have an orange header and sidebar were it not the changes made below. ::: The css can directly into the document (in which case you should set `\| echo: false` to stop it printing). But is probably best in a css or scss file which can be called from the yaml using the css and theme keys respectively. But what if you don't like the colour. The obvious thing is to change the CSS for the colours. ```{css} div.callout-caution { border-left-color: #0d7e14 !important; } div.callout-caution.callout-style-default .callout-title { background-color: #0fe5d0 !important; } ``` Alas, this only changes the sidebar colour. I don't understand why. Fortunately, there is another way. We can make a scss file and change the callout colour there. We can also add the icon. The lines about scss:defaults and scss:rules are important! ```{scss} /*-- scss:defaults --*/ $callout-color-caution: #0a0ffb; /*-- scss:rules --*/ div.callout-caution .callout-icon::before { background-image: url('magnifying-glass-solid.svg') !important; } ``` We can use this scss file by adding it to the yaml ```{yml} --- theme: callout.scss --- ``` ::: callout-caution ## Magnifying glass A callout with our choice of colour and icon. ::: ```{r} #| include: false NULL ``` One challenge is making sure that the icon is in the correct directory. A solution to this is to encode the svg file and add it as data:image as in the original css. We can use `utils::URLencode` to encode the file (hint use single quotes or escape the double quotes in the file.) ```{r} logo <- '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path fill="#0a0ffb" d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352a144 144 0 1 0 0-288 144 144 0 1 0 0 288z"/></svg>' URLencode(logo) ``` So now my scss file looks like ```{scss} /*-- scss:defaults --*/ $callout-color-caution: #0a0ffb; /*-- scss:rules --*/ div.callout-caution .callout-icon::before { background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'%3E%3C!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--%3E%3Cpath fill='%230a0ffb' d='M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352a144 144 0 1 0 0-288 144 144 0 1 0 0 288z'/%3E%3C/svg%3E") !important; } ```