---
title: Quarto vignettes
description: >
  Learn how **pkgdown** works with Quarto vignettes, including currently
  supported features and known limitations.
vignette: >
  %\VignetteIndexEntry{Quarto vignettes}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    collapse: true
    comment: '#>'
---

**pkgdown** uses Quarto only to generate HTML and then supplies its own CSS and
JS. This means that when Quarto introduces new features, **pkgdown** may lag
behind in their support. If you try something that does not work and is not
mentioned explicitly below, please [file an
issue](https://github.com/r-lib/pkgdown/issues) so we can look into it.

## Operation

**pkgdown** turns your articles directory into a Quarto project by temporarily
adding a `_quarto.yml` to your articles. You can also add your own if you want
to control options for all Quarto articles. If you do so and have a mix of
`.qmd` and `.Rmd` files, you need to include the following YAML so that
R Markdown can continue to handle the `.Rmd` files:

``` yaml
project:
  render: ['*.qmd']
```

### GitHub Actions

The `setup-r-dependencies` action will
[automatically](https://github.com/r-lib/actions/tree/v2-branch/setup-r-dependencies#usage)
install Quarto in GitHub Actions if a `.qmd` file is present in your
repository (see the `install-quarto` parameter for more details).

## Limitations

-   Callouts are not currently supported
    (<https://github.com/quarto-dev/quarto-cli/issues/9963>).

-   **pkgdown** assumes that you are using [Quarto vignette
    style](https://quarto-dev.github.io/quarto-r/articles/hello.html), or more
    generally an HTML format with
    [`minimal: true`](https://quarto.org/docs/output-formats/html-basics.html#minimal-html).
    Specifically, only HTML vignettes are currently supported.

-   You cannot customize Mermaid styles with Quarto Mermaid themes. If you want
    to change the colors, provide your own custom CSS as shown in [the Quarto
    docs](https://quarto.org/docs/authoring/diagrams.html#customizing-mermaid).

-   **pkgdown** passes the `lang` setting on to Quarto, but the set of available
    languages is not perfectly matched. Learn more in
    <https://quarto.org/docs/authoring/language.html>, including how to supply
    your own translations.

## Supported features

The following sections demonstrate useful Quarto features so that we can make
sure they work.

### Inline formatting

-   [Small caps]{.smallcaps}

-   Here is a footnote reference[^1]

[^1]: And here is the footnote.

### Code

```{r}
#| fig.alt: A plot of the numbers 1, 2, and 3
1 + 1
2 + 2

plot(1:3)
```

### Figures

::: {#fig-puppies layout-ncol="2"}
![A sketch of a pitbull puppy](pitbull.jpg){#fig-pitbull}

![A sketch of a sharpei puppy](shar-pei.jpg){#fig-shar-pei}

Cute puppies
:::

### Equations

$$
\frac{\partial \mathrm C}{ \partial \mathrm t } + \frac{1}{2}\sigma^{2} \mathrm S^{2}
\frac{\partial^{2} \mathrm C}{\partial \mathrm C^2}
  + \mathrm r \mathrm S \frac{\partial \mathrm C}{\partial \mathrm S}\ =
  \mathrm r \mathrm C
$$ {#eq-black-scholes}

### Cross references

See @fig-puppies for two cute puppies.

Black-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain
the behavior of financial derivatives, most commonly options.

## To-do

-   [ ] Code annotations
-   [ ] Tabsets
-   [x] Citations
-   [x] Task/to do lists
-   [x] Figures
-   [x] Equations
-   [x] Cross-references
-   [x] Footnotes
-   [x] Callouts