What is Quarto?

Quarto is a system for writing documents that mix:

• Prose (regular text, headings, lists, links);
• Code (R, Python, Julia);
• Output (plots, tables, numbers from the code).

Quarto turns the whole thing into a polished HTML page, PDF, Word doc, slide deck, or even a website.

It’s what I used to make the slides you’re looking at right now.

Quarto vs. R Markdown

You might hear about R Markdown (.Rmd files) - it’s Quarto’s older sibling.

• R Markdown came first; it works only with R.
• Quarto is newer; works with R, Python, Julia, and more.
• Both use the same underlying ideas.

In this class we’ll use Quarto (.qmd files) exclusively.

What’s in a .qmd file?

A Quarto document is a plain text file with three kinds of content:

1. A YAML header - settings, surrounded by ---
2. Code chunks - R code, surrounded by ```{r} and ```
3. Markdown text - your prose, with formatting like # headings and **bold**

You can open a .qmd file in any text editor.

A complete example

---
title: "Penguin sizes"
author: "Charles Costanzo"
format: html
---

# Introduction

We have data on 344 penguins
from three species.

```r
library(palmerpenguins)
library(ggplot2)

ggplot(penguins, aes(x = body_mass_g)) +
  geom_histogram(bins = 30, 
                 color = "black", 
                 fill = rgb(0, 206/255, 209/255)) +
  theme_classic() +
  labs(title = "Distribution of Body Mass (grams)",
       x = "Body Mass (grams)",
       y = "Count of Penguins") 
```

The distribution looks roughly **bimodal**, with two peaks.

What’s a YAML header?

The block at the very top, between the two --- lines:

---
title: "Penguin sizes"
author: "Charles Costanzo"
date: "2026-05-21"
format: html
---

This tells Quarto things like:

• What’s the title?
• Who’s the author?
• What format should I render to?

YAML syntax rules

YAML is picky about formatting:

---
title: "My Report"
format:
  html:
    toc: true
    embed-resources: true
---

If your YAML breaks, your document won’t render. Most error messages will point to the line number.

Common format options

format: html

format: pdf

format: docx

You can also render to multiple formats at once:

format:
  html:
    toc: true
  pdf:
    fig-pos: "H"

What’s a code chunk?

A code chunk is a block of R code embedded in your document. It looks like this:

```{r}
2 + 2
```

When you render the document, Quarto:

1. Finds each chunk.
2. Runs the R code inside.
3. Inserts both the code and its output into the final document.

So your readers see your work and its results, side-by-side, always in sync.

Three ways to insert a chunk

1. Keyboard shortcut (recommended):

   • Mac: Cmd + Option + I
   • Windows/Linux: Ctrl + Alt + I

2. Toolbar button: the green +C icon at the top of the editor.

3. Type it yourself: ```{r} on one line, your code, ``` to close.

Running chunks interactively

You don’t have to render the whole document every time. While editing, you can run chunks one at a time:

This is exactly like working in the Console, but your code stays saved in the document.

Chunk options

You can control what each chunk does by adding options at the top, prefixed with #|:

```{r}
#| label: my-plot
#| echo: false
#| fig-width: 6

ggplot(penguins, aes(x = body_mass_g)) +
  geom_histogram()
```

Common options:

When to use which option

You can set options chunk-by-chunk, or globally in the YAML header (more on that in a bit).

The setup chunk

A common pattern: have one chunk at the top of your document that loads packages and sets defaults.

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

library(tidyverse)
library(palmerpenguins)
```

• label: setup is a special name - Quarto runs this chunk first, automatically.
• include: false hides it from the rendered output (your reader doesn’t need to see library(tidyverse)).

Markdown basics

Outside code chunks, your prose is written in Markdown - a simple syntax for formatting plain text.

More Markdown

> This is a block quote.
> It gets a vertical bar on the left.

| Column 1 | Column 2 |
|----------|----------|
| Apple    | Red      |
| Banana   | Yellow   |

Visual editor vs. source editor

RStudio has two ways to edit a Quarto document:

• Source - you see the raw Markdown and YAML. Like editing code.
• Visual - looks more like Google Docs or Word. Buttons for bold, italic, headings, etc.

There’s a toggle in the top-left of the editor pane.

I recommend starting in Visual mode if you’re new to Markdown - you’ll learn the syntax by seeing it appear.

How rendering works

When you click Render, Quarto:

1. Reads your .qmd file.
2. Sends it to knitr, which runs each code chunk in order.
3. Sends the result to pandoc, which converts everything to your target format.
4. Saves the final document next to your .qmd file.

The render button

In RStudio:

• Click Render in the editor toolbar, or
• Press Cmd/Ctrl + Shift + K

The output opens automatically in the Viewer pane (or your browser).

The write / render cycle

Don’t write 200 lines and then try to render. Write a little, render, check it works, write a little more.

If you make a mistake in chunk #47, it’s much easier to find when you only added chunks #45–47 since your last successful render.

Activity debrief

Common stumbling blocks:

• YAML indentation - extra space or missing space at the start of a line breaks everything.
• Forgot to close a chunk - every ```{r} needs a matching ``` on its own line.
• Object not found during render - you typed it in the Console but not in the document. The render uses a fresh session.
• Package not installed - Error: there is no package called 'palmerpenguins'. Install it in the Console.
• Plot doesn’t appear - usually a missing + between ggplot() layers.

Wrap-up: what we covered today

• Recognize a .qmd file as a mix of YAML, prose, and code chunks.
• Write a YAML header with title, author, and format.
• Insert and run code chunks.
• Hide code, output, messages, or warnings with chunk options.
• Use basic Markdown for headings, lists, bold, italic, and links.
• Render a document to HTML.

Wrap-up & looking ahead

Tomorrow: Quiz 1, then the pipe operator and chaining syntax.