Chunk options

Introduction

Chunk options control how a chunk’s code is executed and how its results appear in the rendered document — whether the code is shown, whether messages are printed, how figures are sized, and more.

External Resources

Quarto documentation on chunk options

Quarto specifies chunk options as commented lines beginning with #|, directly below the chunk header, rather than inline in the curly braces:

#| label: data-summary
#| echo: TRUE
#| message: FALSE

Display Control: echo

The echo option controls whether the chunk’s source code itself appears in the rendered document; the result is always shown regardless.

Predict: given the chunk below sets echo: FALSE, will the rendered document show the code, the result, both, or neither?

#| echo: FALSE
mean(c(5, 10, 15))
[1] 10

Explain: as shown above, only the result (10) appears; the mean(c(5, 10, 15)) code itself is hidden. results, warning, and message work the same way for their respective content: each independently controls whether that one type of output is shown, without affecting whether the code or other outputs appear.

Common Mistake

echo: FALSE and include: FALSE are easy to confuse. echo: FALSE hides only the code, while the result (text, table, or plot) still appears. include: FALSE hides both code and result while still running the chunk. Use include: FALSE for setup chunks (like loading packages) that should run silently, and echo: FALSE when you want the reader to see a result without the code that produced it.

Execution Options

  • eval determines whether the chunk is executed at all (TRUE/FALSE).
  • error determines whether rendering continues if the chunk throws an error (TRUE) or stops (FALSE).

A setup chunk that loads packages but shouldn’t appear in the final report combines these ideas:

#| label: setup
#| include: FALSE

library(ggplot2)
library(dplyr)

Figure and Table Options

When a chunk produces a plot or table, these options control its appearance:

  • fig-cap adds a caption.
  • fig-width / fig-height set the dimensions, in inches.
  • fig-align sets the alignment ("left", "center", "right").
#| label: visualization
#| echo: FALSE
#| fig-cap: "Distribution of scores by group."

Caching

Setting cache: TRUE saves a chunk’s results so they don’t need to be recomputed on every render, unless the code itself changes. This is useful for slow computations in large documents, but remember to clear the cache if the underlying data changes without the code changing.

Practice Exercise

You want a chunk’s plot to appear in the rendered report, captioned “Figure 1: Distribution of scores,” but without showing the ggplot code that created it. Which two chunk options do you need, and what would you set them to?

echo: FALSE to hide the code while keeping the plot, and fig-cap: "Figure 1: Distribution of scores" to add the caption.

Back to top