Quarto
One document for your code, your words, and your results
By the end of this session you will be able to:
- Say what Quarto is and why combining code and text helps reproducibility
- Read the three parts of a Quarto document
- Write Markdown text and a code cell that produces output
- Render the same source to HTML, PDF, or slides
- Describe how to publish a document to the web
The problem
You finish an analysis, copy the key numbers and a figure into a Word document, and write up what they mean. A week later a sample turns out to be faulty and has to be removed. Now every number and every figure in your write up is wrong, and you have to find each one, rerun the analysis, and paste the new version in by hand, hoping you do not miss any. This is slow, and how mistakes slip into reports.
Quarto removes this problem. You keep the code, the text, and the results in one document. When the data changes, you rebuild the document and every number and figure updates itself from the code.
This whole site, including the quizzes below, is built with Quarto. By the end of this session you will understand how a page like this is made.
What Quarto is
Quarto is a tool that turns a plain text document containing both writing and code into a finished output, such as a web page, a PDF, or a set of slides. The big idea is that the words, the code, and the results that the code produces all live in one place. Because the results are generated by the code each time, they never fall out of step with the text.
The same source can become different outputs. Write once, then produce a web page for colleagues, a PDF for a supervisor, and slides for a talk, all from the one file.
The three parts of a Quarto document
A Quarto document is a plain text file with the extension .qmd. It has three kinds of content:
- The front matter at the very top, a small settings block written between two lines of
---. It uses a simple format called YAML. - Markdown text, which is your normal writing with light formatting.
- Code cells, blocks of code that Quarto runs, placing their output into the document.
Here is a tiny but complete example:
---
title: "My analysis"
format: html
---
## Results
The average score in our samples is:
```{r}
scores <- c(5.1, 4.9, 6.0, 5.8)
mean(scores)
```The front matter sets the title and says to produce HTML. The ## Results line is a Markdown heading. The code cell computes the mean, and Quarto drops that number into the finished page.
Markdown in one minute
Markdown is a way to format text using a few plain symbols, so the source stays readable. The common pieces:
# A big heading
## A smaller heading
Text can be **bold** or *italic*.
- a bullet list
- another item
A [link](https://quarto.org) and some `inline code`.That is most of what you need. Quarto turns these symbols into proper headings, lists, and links in the output.
Code cells
A code cell is a block of code fenced with triple backticks and a language in braces, such as {python} or {r}. Quarto runs the code and inserts the result, whether that is a number, a table, or a figure.
```{r}
library(readr)
library(dplyr)
data <- read_csv("samples.csv")
data |> summarise(mean_score = mean(score))
```Because the output comes from the code, it always matches the current data. If samples.csv changes, the next render shows the new mean automatically.
Each cell can take options, written on lines starting with #|. A common one is echo, which controls whether the code itself is shown:
```{r}
#| echo: false
mean(data$score)
```With #| echo: false the reader sees only the result, not the code that made it. This is handy for a report where the audience wants the figure, not the script.
Try it out
Here is the same idea, running in RStudio. The code below computes an average. Copy the chunk below into a .qmd file in your RStudio to see the result, then edit the data and run it again to watch the result update. This is exactly what happens when you re-render a Quarto document with new data.
To run a chunk in RStudio, click the green ▶ Run Current Chunk arrow at its top-right, or place your cursor in it and press Ctrl/Cmd + Shift + Enter.
```{r}
measurements <- c(5.1, 4.9, 6.0, 5.8, 5.2)
avg <- mean(measurements)
cat("number of samples:", length(measurements), "\n")
cat("mean:", round(avg, 2), "\n")
```Now your turn. Add the value 7.4 to the vector above, then run the chunk again. Notice that both the count and the mean change on their own, with nothing else edited by hand.
```r
measurements <- c(5.1, 4.9, 6.0, 5.8, 5.2, 7.4)
avg <- mean(measurements)
cat("number of samples:", length(measurements), "\n")
cat("mean:", round(avg, 2), "\n")
```Rendering and formats
To render a document means turning the .qmd source into its finished output (specified in the front matter). You do this from the command line:
quarto render report.qmd # produces report.html
quarto preview report.qmd # opens a live preview that updates as you editTo change the output type, you change one line in the front matter:
format: html # a web page
format: pdf # a PDF document
format: revealjs # a slide deckThe content stays the same, only the kind of output changes.
Hands-on: your first report
Do this on your own machine, where Quarto is installed.
CHALLENGE: create a file report.qmd with a title, a heading, one sentence, and a code cell that prints 2 + 2, then render it to an HTML page.
Try it before opening the solution.
---
title: "My first report"
format: html
---
## Results
This number was produced by code, not typed by hand:
```{python}
2 + 2
```Open report.html in a browser and you will see the heading, your sentence, and the number 4 produced by the code cell.
To run a {r} cell, Quarto needs R installed. Working from RStudio this might seem trivial, but you can use Quarto with other languages, such as Python, rust etc., and on other platforms (e.g. Visual Studio Code, text editor…).
Recap: your Quarto cheat sheet
| Item | What it does |
|---|---|
--- ... --- |
the front matter (settings) at the top of a .qmd |
format: html |
choose the output type (also pdf, revealjs) |
a {python} or {r} cell |
run code and insert its output |
#| echo: false |
hide the code, keep the output |
#| eval: false |
show the code but do not run it |
How does this help us?
Remember redoing every number and figure by hand after one sample changed? You can now keep the code, the text, and the results in one Quarto document, so re-rendering refreshes everything from the code. You can write in Markdown, run code cells, produce HTML, PDF, or slides from the same source, and publish to the web, as this site does.