Getting Started with Quarto

Quarto is an open-source scientific and technical publishing system. It extends R Markdown to support multiple programming languages including Python, R, Julia, and Observable. Quarto produces high-quality documents, books, presentations, dashboards, and websites from your code.

If you already use R Markdown, Quarto will feel familiar. It offers improved performance, better output formats, and a cleaner syntax. This tutorial walks you through creating your first Quarto document.

Why Use Quarto?

Quarto solves several pain points in R Markdown. The syntax is cleaner with the #| option system replacing the chunk label approach. Rendering is faster, especially for documents with many code chunks. Quarto produces output that looks better out of the box, with improved styling for HTML, PDF, and Microsoft Word formats.

Another major advantage is multi-language support. A single Quarto document can contain R, Python, and Julia code in the same file. This makes Quarto ideal for projects that combine different tools. The output formats are consistent regardless of which language your code uses.

Installing Quarto

Quarto is a standalone tool that works with or without RStudio. Install it from the official website:

1. Download the installer for your operating system from quarto.org
2. Run the installer
3. Restart RStudio—Quarto should now appear in the toolbar

You also need the quarto R package:

install.packages("quarto")

Verify the installation by running:

quarto::quarto_version()

This should return a version number like “1.4.0” or higher.

Your First Quarto Document

Open RStudio and select File > New File > Quarto Document. Choose HTML as the output format and give your document a title.

A new file opens with default content. Delete everything and replace it with this simple example:

---
title: "My First Quarto Document"
format: html
---

## Introduction

This is a **Quarto** document. It combines narrative text with code.

## Computing

```{r}
#| echo: true
# Calculate the mean of some numbers
numbers <- c(10, 20, 30, 40, 50)
mean(numbers)
```

## Results

The mean is `r mean(numbers)`.

Save this file as hello-quarto.qmd.

Understanding the Parts

The top section between the --- lines is the YAML header. It specifies metadata like the title and output format. The format: html tells Quarto to render an HTML document.

The ## headings create sections. Code blocks live between the “ ```r ```` markers.

Notice the #| lines inside the code block. These are inline options that control how the code behaves. #| echo: true prints the code alongside its output.

Rendering Your Document

Click the Render button in RStudio’s toolbar. Your browser opens showing the rendered HTML document. The code, output, and narrative text all appear together.

You can also render from the R console:

quarto::quarto_render("hello-quarto.qmd")

Or from the terminal:

quarto render hello-quarto.qmd

Code Chunk Options

Quarto provides dozens of chunk options that control execution and display. Here are the most useful ones:

Option	What it does
`#	echo: false`
`#	include: false`
`#	output: true`
`#	warning: false`
`#	error: false`
`#	collapse: true`
`#	cache: true`
`#	message: false`

Apply these options directly in your chunk:

#| echo: false
#| warning: false
library(ggplot2)

You can set options globally in a setup chunk at the top of your document:

#| include: false
# Set global options
opts <- knitr::opts_chunk$set(
  echo = TRUE,
  warning = FALSE,
  message = FALSE
)

Creating Different Output Formats

One Quarto source can produce multiple outputs. Change the format field in your YAML header:

HTML

format: html

PDF

format: pdf

PDF output requires a LaTeX installation. The tinytex package provides an easy solution:

install.packages("tinytex")
tinytex::install_tinytex()

Microsoft Word

format: docx

This creates a .docx file useful for collaborative workflows. You can even create formatted tables with the kable package:

library(gt)
mtcars[1:5, 1:4] |>
  gt::gt() |>
  gt::tab_header(title = "Motor Trend Cars")

Presentations

Quarto builds presentations too. For Beamer (LaTeX PDF slides):

---
title: "My Presentation"
format: beamer
---

For HTML-based slides using Reveal.js:

---
title: "My Presentation"
format: revealjs
---

Reveal.js presentations support animations, speaker notes, and embedded code. Each level-two heading (##) creates a new slide.

Embedding Plots

Quarto handles plots automatically. Create a plot in a code chunk:

#| label: simple-plot
#| fig-cap: "A simple scatter plot"
library(ggplot2)

ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  theme_minimal()

The #| label: option assigns a name for cross-referencing. The #| fig-cap: adds a caption. Quarto automatically numbers figures and creates proper cross-references.

Tables and Data

Create tables using the kable function from the knitr package:

library(knitr)
kable(head(mtcars), caption = "First rows of mtcars")

Quarto supports many table formats including pipe tables, grid tables, and HTML tables. The syntax is simple—use | characters to define columns:

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

Including External Files

Pull content from other files using includes:

---
title: "My Report"
format: html
include-in-header: header.html
include-after-body: footer.html
---

This keeps large documents organized by separating content into manageable pieces. You can also include code from external files:

```{r}
#| file: scripts/analysis.R
```

What’s Next

You now know the basics of Quarto. From here, explore these areas:

• Parameterized reports that rerun with new data by defining parameters in the YAML
• Quarto websites and blogs for publishing online with the quarto publish command
• Jupyter integration for Python workflows and data science projects
• Custom formatting with Lua filters for advanced document customization
• GitHub Actions for automated document building and deployment

Quarto’s documentation at quarto.org/docs covers these topics in depth. Start with your own documents and experiment with the options that fit your workflow.