Quarto formats

Introduction

So far you’ve seen Quarto used to produce HTML documents. This chapter gives a brief overview of some of the many other types of output you can produce with Quarto.

There are two ways to set the output of a document:

  1. Permanently, by modifying the YAML header:

    title: "Diamond sizes"
format: html

  2. Transiently, by calling quarto::quarto_render() by hand:

    quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")

    This is useful if you want to programmatically produce multiple types of output since the output_format argument can also take a list of values.

    quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))

Output options

Quarto offers a wide range of output formats. You can find the complete list at https://quarto.org/docs/output-formats/all-formats.html. Many formats share some output options (e.g., toc: true for including a table of contents), but others have options that are format specific (e.g., code-fold: true collapses code chunks into a <details> tag for HTML output so the user can display it on demand, it’s not applicable in a PDF or Word document).

To override the default voptions, you need to use an expanded format field. For example, if you wanted to render an html with a floating table of contents, you’d use:

format:
  html:
    toc: true
    toc_float: true

You can even render to multiple outputs by supplying a list of formats:

format:
  html:
    toc: true
    toc_float: true
  pdf: default
  docx: default

Note the special syntax (pdf: default) if you don’t want to override any of the default options.

To render to all formats specified in the YAML of a document, you can use output_format = "all".

quarto::quarto_render("diamond-sizes.qmd", output_format = "all")

Documents

The previous chapter focused on the default html output. There are a number of basic variations on that theme, generating different types of documents. For example:

Remember, when generating a document to share with decision makers, you can turn off the default display of code by setting global options in document YAML:

execute:
  echo: false

For html documents another option is to make the code chunks hidden by default, but visible with a click:

format:
  html:
    code: true

Presentations

You can also use Quarto to produce presentations. You get less visual control than with a tool like Keynote or PowerPoint, but automatically inserting the results of your R code into a presentation can save a huge amount of time. Presentations work by dividing your content into slides, with a new slide beginning at each second (##) level header. Additionally, first (#) level headers can be used to indicate the beginning of a new section with a section title slide that is by default centered in the middle.

Quarto supports a variety of presentation formats, including:

  1. revealjs - HTML presentation with revealjs

  2. pptx - PowerPoint presentation

  3. beamer - PDF presentation with LaTeX Beamer.

You can read more about creating presentations with Quarto at https://quarto.org/docs/presentations.

Dashboards

Dashboards are a useful way to communicate large amounts of information visually and quickly. A dashboard-like look can be achieved with Quarto using document layout options like sidebars, tabsets, multi-column layouts, etc.

For example, you can produce this dashboard:

Quarto dashboard with the title "Diamonds dashboard". The first tab shows four plots of the diamonds dataset. The second tab shows summary statistics for price and carat of diamonds. The third tab shows an interactive data table of the first 100 diamonds.

Using this code:

---
title: "💍 Diamonds dashboard"
format: html
execute:
  echo: false
---

```{r}
#| label: setup
#| include: false

library(tidyverse)
library(gt)
```

::: panel-tabset
## Plots

```{r}
#| layout: [[30,-5, 30, -5, 30], [100]]

ggplot(diamonds, aes(x = carat)) + geom_histogram(binwidth = 0.1)
ggplot(diamonds, aes(x = price)) + geom_histogram(binwidth = 500)
ggplot(diamonds, aes(x = cut, color = cut)) + geom_bar()

ggplot(diamonds, aes(x = carat, y = price, color = cut)) + geom_point()
```

## Summaries

```{r}
diamonds |>
  select(price, carat, cut) |>
  group_by(cut) |>
  summarize(
    across(where(is.numeric), list(mean = mean, median = median, sd = sd, IQR = IQR))
  ) |>
  pivot_longer(cols = -cut) |>
  pivot_wider(names_from = cut, values_from = value) |>
  separate(name, into = c("var", "stat")) |>
  mutate(
    var = str_to_title(var),
    stat = str_to_title(stat),
    stat = if_else(stat == "Iqr", "IQR", stat)
    ) |>
  group_by(var) |>
  gt() |>
  fmt_currency(columns = -stat, rows = 1:4, decimals = 0) |>
  fmt_number(columns = -stat, rows = 5:8,) |>
  cols_align(columns = -stat, align = "center") |>
  cols_label(stat = "")
```

## Data

```{r}
diamonds |> 
  arrange(desc(carat)) |> 
  slice_head(n = 100) |> 
  select(price, carat, cut) |> 
  DT::datatable()
```
:::

To learn more about Quarto component layouts, visit https://quarto.org/docs/interactive/layout.html.

Interactivity

Any HTML documents can contain interactive components.

htmlwidgets

HTML is an interactive format, and you can take advantage of that interactivity with htmlwidgets, R functions that produce interactive HTML visualizations. For example, take the leaflet map below. If you’re viewing this page on the web, you can drag the map around, zoom in and out, etc. You obviously can’t do that in a book, so Quarto automatically inserts a static screenshot for you.

library(leaflet)
leaflet() |>
  setView(174.764, -36.877, zoom = 16) |> 
  addTiles() |>
  addMarkers(174.764, -36.877, popup = "Maungawhau")

The great thing about htmlwidgets is that you don’t need to know anything about HTML or JavaScript to use them. All the details are wrapped inside the package, so you don’t need to worry about it.

There are many packages that provide htmlwidgets, including:

To learn more about htmlwidgets and see a more complete list of packages that provide them visit https://www.htmlwidgets.org.

Shiny

htmlwidgets provide client-side interactivity — all the interactivity happens in the browser, independently of R. On one hand, that’s great because you can distribute the HTML file without any connection to R. However, that fundamentally limits what you can do to things that have been implemented in HTML and JavaScript. An alternative approach is to use shiny, a package that allows you to create interactivity using R code, not JavaScript.

To call Shiny code from an Quarto document, add server: shiny to the YAML header:

title: "Shiny Web App"
format: html
server: shiny

Then you can use the “input” functions to add interactive components to the document:

library(shiny)

textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)

And you also need a code chunk with chunk option context: server which contains the code that needs to run in a Shiny server.

Two input boxes on top of each other. Top one says "What is your name?", the bottom one "How old are you?".

You can then refer to the values with input$name and input$age, and the code that uses them will be automatically re-run whenever they change.

We can’t show you a live shiny app here because shiny interactions occur on the server-side. This means that you can write interactive apps without knowing JavaScript, but you need a server to run them on. This introduces a logistical issue: Shiny apps need a Shiny server to be run online. When you run Shiny apps on your own computer, Shiny automatically sets up a Shiny server for you, but you need a public facing Shiny server if you want to publish this sort of interactivity online. That’s the fundamental trade-off of shiny: you can do anything in a shiny document that you can do in R, but it requires someone to be running R.

For learning more about Shiny, we recommend reading Mastering Shiny by Hadley Wickham, https://mastering-shiny.org.

Websites and books

With a little additional infrastructure you can use Quarto to generate a complete website:

For example, the following _quarto.yml file creates a website from three source files: index.qmd (the home page), viridis-colors.qmd, and terrain-colors.qmd.

project:
  type: website

website:
  title: "A website on color scales"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: viridis-colors.qmd
        text: Viridis colors
      - href: terrain-colors.qmd
        text: Terrain colors

The _quarto.yml file you need for a book is very similarly structured. The following example shows how you can create a book with four chapters that renders to three different outputs (html, pdf, and epub). Once again, the source files are .qmd files.

project:
  type: book

book:
  title: "A book on color scales"
  author: "Jane Coloriste"
  chapters:
    - index.qmd
    - intro.qmd
    - viridis-colors.qmd
    - terrain-colors.qmd

format:
  html:
    theme: cosmo
  pdf: default
  epub: default

We recommend that you use an RStudio project for your websites and books. Based on the _quarto.yml file, RStudio will recognize the type of project you’re working on, and add a Built tab to the IDE that you can use to render and preview your websites and books. Both websites and books can also be rendered using quarto::render().

Read more at https://quarto.org/docs/websites about Quarto websites and https://quarto.org/docs/books about books.

Other formats

Quarto offers even more output formats:

See https://quarto.org/docs/output-formats/all-formats.html for a list of even more formats.

Learning more

To learn more about effective communication in these different formats we recommend the following resources: