2  Day 2: Document Anatomy: YAML, Chunks, and the Execution Model

2.1 Learning objectives

By the end of this day you should be able to:

  • Translate an R Markdown YAML header into its Quarto form.
  • Rewrite chunk options from the header line into the #| cell-option syntax.
  • Set document-wide execution defaults in place of knitr::opts_chunk$set.
  • Control execution with echo, eval, warning, message, and freeze.
  • Distinguish the knitr and jupyter engines and state when each applies.
  • Use inline code in the Quarto style.

2.2 Lecture

We begin inside the document. Day 1 showed that an .Rmd renders unchanged; today we make the small but consequential changes that turn an .Rmd into an idiomatic .qmd. That is, we translate the anatomy.

2.2.1 YAML front matter differences

The Quarto YAML header is close to the R Markdown one, with a few renamings. Recall that R Markdown uses output: with a package-format key; Quarto uses format: with a short name.

# R Markdown
output:
  html_document:
    toc: true
# Quarto
format:
  html:
    toc: true

We note that many sub-options keep their names, so the translation is often mechanical.

2.2.2 The #| cell-option syntax

The most visible change is where chunk options live. In R Markdown they sit on the header line; in Quarto they move onto #| comment lines inside the chunk, written as YAML.

We observe that each option is a YAML key, lowercased and hyphenated (fig-cap, not fig.cap). This is the single most common edit in a migration, and Day 5 automates it.

2.2.3 Execution options in place of opts_chunk

Where R Markdown sets global chunk defaults with knitr::opts_chunk$set(...) in a setup chunk, Quarto sets them once in the YAML under execute:.

execute:
  echo: true
  warning: false
  message: false

We note that a per-chunk #| option overrides the document-wide default, exactly as a per-chunk option overrode opts_chunk in R Markdown.

2.2.4 Controlling what runs and what shows

Five options carry most of the daily load. We describe each briefly:

  • eval decides whether the code runs.
  • echo decides whether the code is shown.
  • warning and message decide whether those streams appear.
  • freeze decides whether Quarto re-executes a cell at all, which we develop fully on Day 5.
# shown but not run
fit <- lm(dist ~ speed, data = cars)

2.2.5 The knitr and jupyter engines

Quarto chooses an engine per document. For R content it uses knitr, the same engine R Markdown used, so behavior matches. For Python content it can use jupyter. We set the engine explicitly when needed.

engine: knitr

We note that a document mixing R and Python is possible, but that the everyday R Markdown user will stay on knitr, and nothing changes for them.

2.2.6 Inline code

Inline code carries over directly. Recall the R Markdown form 50; Quarto uses the identical syntax, so inline expressions need no translation.

The dataset has 50 rows.

2.3 Worked example: modernizing a setup chunk

We return to enrollment-report.qmd from Day 1. It still carries an R Markdown setup chunk and header-line options. Our task is to translate them into idiomatic Quarto without changing the rendered result.

The document opens with a familiar setup chunk:

knitr::opts_chunk$set(echo = FALSE, warning = FALSE,
                      message = FALSE)

We lift those defaults into the YAML and delete the setup chunk:

execute:
  echo: false
  warning: false
  message: false

Next we find a figure chunk written the R Markdown way:

::: {.cell}

:::

and rewrite it in the Quarto way:






::: {.cell}

```{.r .cell-code}
barplot(table(c('A', 'B', 'A')))

:::

We render again and compare against Day 1’s output. The result is identical, which is the goal: the translation changes the source style, not the rendered document. We have now removed the last R Markdown idioms from the report, and it is ready for the output features of Day 3.

2.4 Homework

Attempt each problem in your own environment before checking the solution.

  1. Translate a header. Given an R Markdown header that uses output: html_document with a table of contents, write the equivalent Quarto format: block.

  2. Move options inside. Take a chunk written as ```{r, echo=FALSE, fig.width=6} and rewrite it with the #| cell-option syntax.

  3. Global defaults. Replace a knitr::opts_chunk$set(echo = FALSE, message = FALSE) setup chunk with the equivalent execute: YAML.

  4. eval versus echo. Write two chunks: one shown but not run, and one run but not shown. State which option controls each.

  5. Override a default. With document-wide echo: false, write a single chunk that nonetheless shows its code.

  6. Inline code. Write a sentence that reports the number of rows of cars using inline code.

  7. Name the engine. State which engine Quarto uses for an R-only document, and where you would set it explicitly.

2.5 Solutions

Problem 1. Placeholder. Give the format: html block with toc: true.

Problem 2. Placeholder. Show the chunk rewritten with #| echo: false and #| fig-width: 6.

Problem 3. Placeholder. Show the execute: block with echo: false and message: false.

Problem 4. Placeholder. Identify eval: false for shown but not run, and echo: false for run but not shown.

Problem 5. Placeholder. Show a chunk carrying #| echo: true that overrides the global default.

Problem 6. Placeholder. Show the inline 50 sentence.

Problem 7. Placeholder. State knitr for R-only content and the engine: knitr YAML key.

2.6 What’s next

Day 3 turns from anatomy to output. We shall render the same content to HTML, PDF, Word, and revealjs slides; handle figures and tables with captions; use Quarto’s native cross-references for figures, tables, and sections; add citations with a CSL style; and place content in callouts and the margin. Keep enrollment-report.qmd; Day 3 adds cross-referenced figures and tables to it.