Chunk Options

1 Chunks have options

Without applying any options, quarto will simply include both the code and output into the rendered document. This will include messages, error messages, warnings etc. Let’s take a look at what that might mean:

library(tidyverse)

Warning: package 'ggplot2' was built under R version 4.4.2

── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.1.4     ✔ readr     2.1.5
✔ forcats   1.0.0     ✔ stringr   1.5.1
✔ ggplot2   3.5.1     ✔ tibble    3.2.1
✔ lubridate 1.9.3     ✔ tidyr     1.3.1
✔ purrr     1.0.2     
── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
✖ dplyr::filter() masks stats::filter()
✖ dplyr::lag()    masks stats::lag()
ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors

2 Applying options?

We can stipulate how it is that quarto should deal with any given chunk in a number of ways:

Note

Note that there is a fourth way to include yaml chunk options: If you create a Quarto Project (instead of just a document) then there will be a _quarto.yml file that contains yaml for all documents created in that project.

There are three main ways to include chunk options (in this example we’d be telling quarto not to include the code in the rendered document).

Chunk header

Chunk yaml

Document yaml

If you set a chunk option in the document yaml then the option will apply to all chunks (unless specified differently in a specific chunk).

3 Quarto Chunk Options

Here are the most commonly used chunk options that you can insert either into the beginning of a chunk or into the yaml at the beginning of your document if you want them to apply to all chunks:

3.1 Execution options

3.2 Output options

3.3 Figure options

And here is some information about the default values and optional arguments for the chunk yaml options:

• echo: Controls whether the code is shown in the rendered document.

  • Values: true (show code), false (hide code).

  • Default: true.

• eval: Controls whether the code is evaluated (runs)

  • Values: true (evaluate), false (do not evaluate).

  • Default: true.

• include: Controls whether the output of the chunk is included in the rendered document.

  • Values: true (include output), false (do not include output).

  • Default: true.

• warning: Controls whether warnings generated by the code are shown in the document.

  • Values: true (show warnings), false (hide warnings).

  • Default: true.

• message: Controls whether messages generated by the code are shown in the document.

  • Values: true (show messages), false (hide messages).

  • Default: true.

• error: Controls whether errors generated by the code are shown.

  • Values: true (show errors), false (hide errors).

  • Default: true.

• results: Controls how the results of the code are displayed.
  • Values: "markup" (formatted output), "asis" (raw output as-is), "hide" (no output).
• fig.show: Controls whether figures generated by the chunk are displayed.

  • Values: "hide" (do not display figures), "hold" (display after code execution).

  • Default: "hold".

• fig.cap: Provides a caption for a figure generated by the code.
  • Value: A string representing the caption.
• fig.width and fig.height: Specify the width and height of the figures in inches.
  • Values: Numeric values representing width/height in inches.
• fig.align: Controls the alignment of figures.

  • Values: "left", "right", "center".

  • Default: "center".

• out.width and out.height: Specify the output width and height for images in the document.
  • Values: Can use units such as % or px.
• collapse: Controls whether consecutive outputs are combined together.

  • Values: true (combine), false (keep separate).

  • Default: false.

• tidy: Controls whether the code is tidied/pretty-printed.

  • Values: true (tidy code), false (do not tidy).

  • Default: false.

• echo.line: Controls which lines of code to echo.
  • Value: A vector of line numbers (e.g., 1:3).
• code-link: Adds a link next to the code chunk to navigate back to the original source.
  • Values: true (add link), false (do not add link).
• code-summary: Provides a summary that users can click on to reveal the code.
  • Value: A string representing the summary text (e.g., "Click to view code").

4 What’s next

In the next lesson we’ll learn about how hyperlink and reference figures and tables in your document as well as execute in-line code to insert data points directly into the text of your document.