23 Reproducible Reports with Quarto
A number read off the console and typed into a sentence takes four seconds, and it is a very reasonable thing to do. It also breaks the connection between the analysis and the claim. Suppose the data are corrected and the analysis is re-run. The figures update and the sentence does not, and nothing tells you so. Literate programming closes that gap. The sentence carries the code that computes its number, so the number cannot drift from the analysis. Quarto is the current tool for doing this in R. Most of this chapter is about the few places where it can still let a stale number through.
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
Donald E. Knuth, Literate Programming (1984)
Reading time. About 35 minutes.
You’ll need. Chapter 6 for an installed Quarto (quarto check confirms it), and Chapter 18 for the row-count check in the worked example. The executed code uses base R and the quarto command-line tool, so it needs no library() call.
You’ll be able to.
- Replace every number typed into prose with inline code, and show that the numbers change when the data do.
- Label figures, tables, and sections so that a reference to a missing one is reported at render time instead of going unnoticed.
- Choose between
freezeandcachefor an expensive computation, and predict when each will serve a stale result. - Render one report per site from a single parameterized source.
- Control where LaTeX places figures and tables in PDF output.
- Diagnose a failing render from its log, and find the silent failures a successful render can hide.
Outline.
If these answers come quickly, skip to the next chapter. The answers are in Section 23.14.
- What is ‘literate programming’, and how does a
.qmdfile embody it? - Given a Quarto document that contains R code and prose, what single command renders it to an HTML file, and how does Quarto decide which output format to produce?
- What is the purpose of
execute: freeze: autoin a Quarto project, and what problem does it solve? - Why do tables and figures in rendered PDFs often appear in unexpected places, and what do
fig-posandtbl-posdo?
23.1 Literate programming and the inline number
Donald Knuth’s idea (Knuth, 1984) was that source code and prose should live in one document, with the prose explaining the code as one person would explain it to another. Quarto implements it with code chunks and prose interleaved in a .qmd file. The part that matters most for a statistician is the smallest: an inline expression, which puts a computed value inside a sentence.
We compared the 30-day composite outcome between the randomized
arms.
```{r}
obs <- trial[!is.na(trial$event_30d), ]
rates <- tapply(obs$event_30d, obs$arm, mean)
```
Readmission or death within 30 days occurred in
`{{r}} round(100 * rates[["Usual care"]], 1)`% of patients
under usual care.Rendering runs the chunk, evaluates the inline expression, and writes its value into the sentence. Re-render after the data change and the sentence changes with them. Copying the number into Word instead is where ‘I forgot to update Table 2’ comes from.
What to compute inline is the author’s decision, and the rule is simple: any number that depends on the data. That includes the sample size in the abstract, the count of exclusions in the methods, every estimate and interval, and the p-value that a reviewer will check against the table. A manuscript with p < 0.05 typed into it is correct only until the next extract.
23.1.1 The minimum document
---
title: "HF-HOME interim summary"
format: html
---
Some prose here.
```{r}
1 + 1
```Save it as analysis.qmd and render it from the shell with quarto render analysis.qmd, which writes analysis.html. The format: key decides the output; with none, Quarto writes HTML. One source can produce several formats. That keeps a single source of truth for the website, the journal, and the collaborator who edits only in Word. The price is the set of constraints in Table 23.1.
format: to render them all at once.
| Format | Command | What it cannot carry |
|---|---|---|
| HTML | quarto render analysis.qmd --to html |
Nothing that matters here; it is the most capable target |
quarto render analysis.qmd --to pdf |
Interactive HTML widgets; needs a LaTeX installation (quarto install tinytex) |
|
| Word | quarto render analysis.qmd --to docx |
Fine typographic control; LaTeX math is converted and may need checking |
Question. Your manuscript says ‘The mean age was 67.3 years (SD 12.1)’, typed in from the console. What is wrong with this, and what is the Quarto fix?
Answer. The numbers are detached from the data. Re-run the analysis on corrected data and the prose still says 67.3 and 12.1, while every table beside it has moved. The fix is inline computation:
The mean age was `{r} round(mean(d$age, na.rm = TRUE), 1)`
years (SD `{r} round(sd(d$age, na.rm = TRUE), 1)`).
The prose is now computed at render time, so a re-render on new data updates it. It is still possible for the rendered document to be stale, if the code was not re-run; Section 23.3 is about when that happens.
23.1.2 Exercises
- Write the sentence ‘The mean age at index discharge was X years (SD Y), and Z patients were older than 89’ for the HF-HOME demographics file (
file.path('..', 'data', 'raw_data', 'hfhome', 'demographics.csv')), with every number inline. Compute the values in a chunk so that you can check the rendered sentence against them.
The sentence, with its setup chunk:
```{r}
#| include: false
demo <- read.csv(file.path("..", "data", "raw_data", "hfhome",
"demographics.csv"),
colClasses = c(patient_id = "character"))
```
The mean age at index discharge was
`{{r}} round(mean(demo$age), 1)` years
(SD `{r} round(sd(demo$age), 1)`), and
`{{r}} sum(demo$age > 89)` patients were older than 89.The values it should render:
The count of patients over 89 matters beyond this chapter: ages above 89 are an identifier under the HIPAA (Health Insurance Portability and Accountability Act) Safe Harbor method (Chapter 4), so a de-identified extract would not let you compute it, and the sentence would have to change.
23.2 Chunks, cross-references, and citations
23.2.1 Chunk options
A chunk’s options sit at its top, one per line after #|:
```{r}
#| label: fig-outcome-by-arm
#| fig-cap: "30-day readmission or death by randomized arm"
#| fig-width: 6
#| echo: false
ggplot(obs, aes(arm, fill = factor(event_30d))) +
geom_bar(position = "fill")
```| Option | Effect | Typical use |
|---|---|---|
echo: false |
Runs the code, shows the output, hides the code | Papers; keep true for teaching and review |
include: false |
Runs the code, shows nothing | Setup chunks that read data and load packages |
eval: false |
Shows the code, does not run it | Code that must not execute, such as a deployment command |
warning: false, message: false
|
Suppresses warnings or messages | A chunk whose warnings you have read and judged harmless |
label: fig-... |
Names the chunk and makes it a cross-reference target | Every figure and table you refer to |
fig-cap, fig-width, fig-height
|
Caption and size of the figure | Every figure |
cache: true |
Reuses the chunk’s stored result (Section 23.3) | An expensive chunk in a single document |
The front matter is the YAML (YAML Ain’t Markup Language) header between the --- lines at the top of the file. Set defaults for every chunk under its execute: key, for example echo: false, and override them per chunk.
A global warning: false hides the warnings that make failures loud. dplyr‘s many-to-many join warning (Chapter 18), glm()’s ’fitted probabilities numerically 0 or 1’, and a date parser’s ‘failed to parse’ are each the only sign of a wrong number. With warning: false set under execute:, none of them reaches the rendered document, where a reader would see it. Leave warnings on while the analysis is changing. Suppress them per chunk, after you have read them.
23.2.2 Cross-references
Label a figure, table, equation, or section, and refer to it by label; Quarto numbers it and writes ‘Figure 3’ or a link.
See @fig-outcome-by-arm for the outcome by arm.
```{r}
#| label: fig-outcome-by-arm
#| fig-cap: "30-day readmission or death by randomized arm"
ggplot(obs, aes(arm, fill = factor(event_30d))) + geom_bar()
```| Prefix | Labels | Where the label goes |
|---|---|---|
fig- |
Figures | The chunk’s label: option |
tbl- |
Tables | The chunk’s label:, or {#tbl-...} after a pipe table’s caption |
eq- |
Equations |
{#eq-...} after the closing $$
|
sec- |
Sections |
{#sec-...} after the heading, as in # Methods {#sec-methods}
|
The same source produces hyperlinks in HTML, numbered references in PDF, and field codes in Word.
23.2.3 Citations
Point the front matter at a BibTeX file and a citation style, and cite by key:
bibliography: references.bib
csl: https://www.zotero.org/styles/jamaThis builds on prior work [@bryan2019happygit; @marwick2018rrtools].
@wickham2019advr discusses copy-on-modify in detail.
[@key] gives a parenthetical citation and @key a textual one; separate several keys with semicolons. The CSL (Citation Style Language) file sets the journal’s format, so changing journals means changing one line. Start the .bib file on the first day: backfilling the citations of a finished draft is slow, and a methods section whose references were typed by hand cannot be reformatted or checked.
Question. You write @fig-trajectory in the prose, but the chunk that should produce the figure is display-only, so the label never exists. What happens when you render, and why is that better than writing ‘Figure 3’?
Answer. Quarto prints WARN: Unable to resolve crossref @fig-trajectory and renders the reference as ?@fig-trajectory. The build completes, but the defect is visible in the log and in the output. Written as ‘Figure 3’, the reference is only a string. Insert a figure earlier and the sentence points at the wrong one, with nothing to warn you. Cross-references turn the errors that revision introduces into build warnings. Inline code does the same for numbers.
23.2.4 Exercises
- Convert a short
.Rscript of yours into a.qmdthat renders to both HTML and PDF, with one captioned figure, one cross-reference to it, and one citation from a.bibfile.
A correct result renders both formats without a WARN line, shows ‘Figure 1’ (or a link) where you wrote the reference, and ends with a reference list in both outputs. Two failures are common. A reference rendered as ?@fig-... means the label is missing or misspelled, or the chunk did not run. A citation rendered as its bare key, with a ‘citation not found’ warning, means the key is not in the .bib file the front matter names. If the PDF fails with a LaTeX error, run quarto install tinytex.
23.3 Freeze and cache
A ten-second analysis can run on every render; a ten-minute bootstrap or an MCMC (Markov chain Monte Carlo) fit cannot. Quarto offers two ways to store a result and reuse it. They differ in scope, in what makes them re-run, and in when they are ignored (Table 23.4). The rule for both is the same. Store a result only when the computation is expensive and deterministic, and re-run anything that is cheap or could change.
freeze and cache compared.
freeze (Quarto) |
cache (knitr) |
|
|---|---|---|
| Set with |
execute: freeze: auto in _quarto.yml or a document’s front matter |
cache: true on a chunk, or under execute:
|
| Scope | A whole document | One chunk |
| Applies | Only inside a Quarto project (a directory with _quarto.yml) |
In any document |
| Stored in |
_freeze/ at the project root |
A <document>_cache/ directory beside the document |
| Re-executes when |
auto: any change to the document’s source, even one character, re-runs the whole document; true: never during a project render; false (the default): always |
The chunk’s code or options change |
| Ignored when | You render a single file or a subdirectory, which always executes | Never ignored by the kind of render |
| Does not notice | Changed data files, packages, or R version | Changed data files, packages, or upstream chunks (unless dependson names them) |
| Commit to Git? | Commonly, so that collaborators and automated builds reuse expensive results | Usually not |
The two consequences in the ‘Ignored when’ row often surprise people. First, quarto render analysis.qmd executes the document whatever freeze says, so freeze speeds up only full project renders. Second, a stand-alone .qmd outside any project has no _freeze/ at all. For chunk-level reuse there, use cache: true.
_freeze/ can be committed to Git. A collaborator or a continuous-integration (CI) build that renders the project then reuses the stored results instead of re-running a long analysis (Chapter 8 discusses the merge conflicts this can bring). We note that the stored results are whatever the last execution produced. A randomized chunk that sets its own seed reproduces them when it does re-run. One that does not set a seed will produce different numbers from the stored ones.
Neither freeze nor cache sees the data. Both decide whether to re-run by looking at code. Suppose you replace data/trial.csv with a new extract. A project render under freeze: auto then serves the old numbers, with no warning, because the .qmd did not change. A cached chunk that reads the file does the same. This is the typed-number failure again, one level down. The worked example below shows it happening. After a data change, render the document itself, or delete its entry in _freeze/. For a cached chunk, add cache.extra: !expr tools::md5sum("data/trial.csv"), which makes the file’s checksum part of what the cache compares.
Question. A project uses freeze: auto. You fix a typo in the discussion of results.qmd and run quarto render. Which chunks re-execute?
Answer. Every chunk in results.qmd, and none in any other document. Freeze works per document, so any change to the source, prose included, invalidates the whole document’s stored results. If you wanted only the expensive chunk protected, that is cache: true on the chunk, whose key is the chunk’s own code.
23.3.1 Exercises
- For each scenario, say whether the code re-executes:
- project render,
freeze: auto, prose edited; - project render,
freeze: auto, data file replaced; -
quarto render report.qmdwithfreeze: true; -
cache: truechunk, an upstream chunk edited; -
cache: truechunk, its own code edited.
- project render,
| Scenario | Re-executes? | Why |
|---|---|---|
| (a) | Yes, the whole document |
auto watches the source, and prose is source |
| (b) | No | Freeze does not see data files; the results are stale |
| (c) | Yes | A single-file render ignores freeze
|
| (d) | No | The cache key is the chunk’s own code; add dependson
|
| (e) | Yes | The chunk’s code is its cache key |
Scenarios (b) and (d) are the dangerous ones, because each produces a document that looks current.
23.4 Worked example: a report that survives a new extract
The example builds a one-paragraph HF-HOME report in a temporary Quarto project with freeze: auto, renders it against an interim extract, then replaces the data with the full extract and renders it twice more. It runs the real quarto command, so the output below is what you would see.1
1 The env argument passes this session’s library paths to the R process that Quarto starts, so that it finds the same packages. In a terminal you would type quarto render alone.
hf_dir <- file.path("..", "data", "raw_data", "hfhome")
read_hf <- function(file) {
read.csv(file.path(hf_dir, file),
colClasses = c(patient_id = "character"))
}
randomization <- read_hf("randomization.csv")
outcomes <- read_hf("outcomes.csv")
trial <- merge(
randomization[c("patient_id", "site", "rand_date", "arm")],
outcomes[c("patient_id", "event_30d")],
by = "patient_id"
)
stopifnot(nrow(trial) == nrow(randomization),
!anyDuplicated(trial$patient_id))
proj <- file.path(tempdir(), "hfhome-report")
unlink(proj, recursive = TRUE)
dir.create(file.path(proj, "data"), recursive = TRUE)
writeLines(c("project:", " type: default",
"execute:", " freeze: auto"),
file.path(proj, "_quarto.yml"))
writeLines(c(
'---',
'title: "HF-HOME: 30-day outcomes by arm"',
'format: gfm',
'---',
'',
'```{r}',
'#| include: false',
'd <- read.csv("data/trial.csv")',
'obs <- d[!is.na(d$event_30d), ]',
'pct <- function(a) round(100 * mean(obs$event_30d[obs$arm == a]), 1)',
'```',
'',
'Of `r nrow(d)` patients randomized, `r nrow(obs)` had the',
'primary outcome ascertained. Readmission or death within 30',
'days occurred in `r pct("Usual care")`% under usual care and',
'`r pct("Home health")`% with home health.'
), file.path(proj, "report.qmd"))
render_report <- function(target, ...) {
r_libs <- paste0("R_LIBS=",
paste(.libPaths(), collapse = .Platform$path.sep))
status <- system2("quarto", c("render", target, ..., "--quiet"),
env = r_libs)
stopifnot(status == 0)
md <- readLines(file.path(proj, "report.md"))
paste(md[nzchar(md)][-1], collapse = " ")
}The report’s inline expressions use the R Markdown spelling, a backtick, r, and a space, which Quarto’s knitr engine also accepts.2 In your own documents use the {r} spelling shown earlier in the chapter.
2 Quarto rewrites every {r} inline expression in a document before any chunk runs, including one inside a string in a chunk. A chapter written in Quarto therefore cannot write that spelling into a file this way.
The interim extract holds the patients randomized by the end of March 2025. Render the whole project, as a build script or CI would:
interim <- trial[trial$rand_date <= "2025-03-31", ]
write.csv(interim, file.path(proj, "data", "trial.csv"),
row.names = FALSE)
render_report(proj)
#> [1] "Of 1555 patients randomized, 1458 had the primary outcome ascertained. Readmission or death within 30 days occurred in 22.4% under usual care and 22.1% with home health."The full extract arrives. Replace the data file and render the project again:
The paragraph has not changed. Every number in it is computed, and every number is wrong. The reason is that freeze: auto saw an unchanged report.qmd and served the stored results. Render the document itself, which always executes:
current <- render_report(file.path(proj, "report.qmd"))
current
#> [1] "Of 2432 patients randomized, 2269 had the primary outcome ascertained. Readmission or death within 30 days occurred in 23.7% under usual care and 21.1% with home health."Compute the counts independently of the report and confirm that the current render states them and the stale one does not.
In your own project, the same check is a test (Chapter 27): read the rendered output and assert that it contains the numbers the analysis computes.
Use a model to convert typed numbers to inline code, and check the result by changing the data.
Context. Below are the data dictionary for
trial.csv(patient_id,site,rand_date,arm,event_30d) and the results paragraph of a Quarto report whose setup chunk readsdata/trial.csvintod. Every number in the paragraph was typed by hand.Constraints. Replace every number that depends on the data with an inline
{r}expression computed fromd, defining any helper objects in the setup chunk. Use base R. Do not change the wording, and do not write any data-dependent number as a literal, including denominators inside an expression.Criteria. List each number you replaced and the expression that now computes it. The document must render, and every number in the paragraph must change when it is rendered against a different extract.
Failure mode. The model computes a value itself and writes it back as a literal. Or it writes sum(d$event_30d) / 2432, an inline expression with a typed denominator. That expression renders the right number today and a wrong one on the next extract. Check. Render against the interim and the full extracts, as above, and compare the two paragraphs number by number (regmatches(x, gregexpr("[0-9.]+", x)) lists them). A number that is the same in both is typed or must be justified. Then read each listed expression for constants. A dictionary and a paragraph hold no patient data, so they may go to any approved tool (Section 12.3).
Question. In the worked example, the stale render contained no typed numbers. Why did it still report the interim results, and why would no reviewer reading the output notice?
Answer. Inline code guarantees that a number is computed when the document executes. It says nothing about whether the document executed. freeze: auto skipped execution because the source was unchanged, so the computed numbers were from the previous run. The paragraph is internally consistent and plausible, which is what makes it dangerous (Habit 8). A line in the report that states which extract it used, as in Exercise 4, makes the staleness visible.
23.4.1 Exercises
- Add a sentence to the worked example’s report that states the extract it was computed from, using the latest randomization date in
d, so that a stale render announces itself.
Computed from the extract of patients randomized through
`{{r}} max(d$rand_date)`.
The stale render in the worked example would then name a date in March 2025 beside numbers the reader believes are final. A reader can catch that. Stating provenance in the output is a cheap form of the assertion habit. It does not prevent the stale render. However, it turns a silent failure into a visible one.
23.5 Parameterized reports
A parameter lets one .qmd render against different inputs: one report per site in a multi-site trial, per sensitivity analysis, or per institution. Declare the parameter and its default in the front matter, and read it as params$site:
params:
site: "All"Render a variant from the shell (display-only):
quarto render report.qmd -P site:"Site C"Or from R with the quarto package:
quarto::quarto_render("report.qmd",
execute_params = list(site = "Site C"),
output_file = "report-site-c.html")A parameterized report renders the same document against different data; a website (Section 23.6) renders different documents into one whole. A multi-site trial may use both: one parameterized report per site, collected into a site with an overview page.
Question. Why give the report a site parameter rather than copying it into five files, one per site?
Answer. Five copies drift. A fix to the denominator made in one copy is missing from the other four, and nothing reports the difference. With a parameter there is one source, so a correction reaches every site’s report at the next render.
23.5.1 Exercises
- Give the worked example’s report a
siteparameter that defaults to"All"and, when set, restrictsdto that site. Render it for Site C and check the patient count against the data.
site_report <- readLines(file.path(proj, "report.qmd"))
site_report <- append(site_report,
c("params:", ' site: "All"'), after = 3)
site_report <- sub(
'd <- read.csv("data/trial.csv")',
paste('d <- read.csv("data/trial.csv");',
'if (params$site != "All") d <- d[d$site == params$site, ]'),
site_report, fixed = TRUE
)
writeLines(site_report, file.path(proj, "report.qmd"))
site_c <- render_report(file.path(proj, "report.qmd"),
"-P", shQuote("site:Site C"))
site_c
#> [1] "Of 498 patients randomized, 462 had the primary outcome ascertained. Readmission or death within 30 days occurred in 23.9% under usual care and 18.5% with home health."
stopifnot(grepl(sprintf("Of %d patients", sum(trial$site == "Site C")),
site_c, fixed = TRUE))The default "All" keeps the unparameterized render unchanged, and the filter sits in the setup chunk, so every inline number below it is computed for the chosen site. The stopifnot() is the check: the count in the rendered sentence equals the count computed from the data.
23.6 Reference: front matter and websites
23.6.1 Front matter
The keys used in this chapter, with one example each:
| Key | Sets | Example |
|---|---|---|
title, author, date
|
Title block | date: today |
format |
Output formats and their options |
html: {toc: true}, pdf: default
|
execute |
Defaults for every chunk |
echo: false, freeze: auto
|
bibliography, csl
|
Citations and their style |
references.bib, a CSL URL |
params |
Parameters and their defaults | site: "All" |
Authors take a list of names with optional affiliation and orcid fields. Format options nest under each format, so HTML and PDF can have different figure sizes from one source.
23.6.2 Websites
A directory of .qmd files governed by a _quarto.yml with project: type: website renders to a website: linked pages with shared navigation, theme, and search. This book is the same machinery with type: book. The minimum is a _quarto.yml naming the pages and an index.qmd landing page:
project:
type: website
website:
title: "HF-HOME analysis"
navbar:
left: [index.qmd, methods.qmd, results.qmd]quarto render builds the site into _site/, quarto preview serves it with live reload, and quarto publish gh-pages (or netlify, quarto-pub, connect) publishes it. For a research team, a site is the natural form of an internal analysis portal. It carries every guarantee of this chapter. It is also rebuilt on every push by the CI workflow of Section 27.9, whereas a PDF that is emailed around goes stale.
23.7 Accessible documents
A document that renders without a warning can still be unusable to a reader on a screen reader or a magnifier. Quarto does not check this for you. It only gives you the markup. Used correctly, that markup lets assistive technology navigate the document the way a sighted reader scans it.
23.7.1 Heading levels and the document outline
A screen reader user commonly jumps between headings rather than reading linearly, the way a sighted reader skims a table of contents. That only works if the heading levels nest without skipping. That is, a ## section’s subsections are ###, never #### chosen because it looked like the right size. Quarto numbers # through ###### the same way regardless of level skipped. A rendered page can therefore look fine while its outline is unusable. The only way to catch a skipped level is to read the headings as a list. For example, use the browser’s accessibility tree or pandoc -t native on the rendered source. Use heading level for structure. Use .smallcaps, bold, or a callout for visual emphasis that is not a new section.
23.7.2 Caption every table, and keep its text with it
A {#tbl-...} caption (Table 23.3) lets you write @tbl-outcomes. A screen reader also announces the caption text together with the table. For some readers, that is the only description they get of what the columns contain. A pipe table or gt/gtsummary output with no caption reaches a screen-reader user as an unlabeled grid of numbers. Write the caption so it states what the table shows. This is the same discipline Section 20.5 asks of a figure’s fig-alt. A caption that merely repeats ‘Table 1’ states nothing a screen reader did not already announce.
23.7.3 Alt text for figures
Every figure needs a fig-alt string. What distinguishes a useful one from a decorative one is a figure-specific judgment about what a visualization does and does not need to say. Section 20.5 teaches that judgment with this book’s own figures as examples. The Quarto-specific part is only the chunk option itself. Set fig-alt on every chunk that produces output a reader cannot otherwise decode. That includes a table rendered as an image by some PDF pipelines (Section 23.8 touches a related PDF quirk).
23.7.4 Accessibility of HTML, PDF, and Word
Table 23.1 lists what each format cannot carry. The formats also differ in accessibility. HTML is the most accessible target. A modern screen reader reads its heading structure, table markup, and alt attributes directly, and the reader controls font size and contrast in the browser. PDF is the least accessible by default. Figures and non-tagged tables in a PDF can read as unlabeled images to assistive technology. Keyboard-only navigation by heading is unreliable even in a well-structured PDF, unless it was exported with tagging enabled. LaTeX-based PDF (the engine quarto render --to pdf uses by default) does not do that without extra configuration. Word sits between the two. fig-alt text and table captions both carry into the .docx’s accessibility metadata. A sighted reader with low vision also benefits from Word’s own zoom and high-contrast modes. However, heading navigation depends on the document using Word’s built-in heading styles rather than visual formatting. Quarto’s conversion uses those styles by default.
Suppose a document’s primary audience may include a screen-reader user, and the choice of format is yours to make. Then prefer HTML, and offer PDF as a secondary, print-oriented format rather than the only one. A report that must ship as PDF for a journal or a regulatory submission is not thereby exempt from headings, captions, and alt text. Those three practices are what a tagged, accessible PDF is built from. That holds even though Quarto’s default LaTeX pipeline does not produce the tagging automatically.
Question. A report renders to both HTML and PDF from one source, with every figure’s fig-alt set and every table captioned. Is the PDF now as accessible to a screen-reader user as the HTML?
Answer. Not necessarily. fig-alt and table captions are markup Quarto writes into both outputs. However, the default LaTeX PDF pipeline does not tag the PDF’s reading order, headings, or table structure the way HTML’s DOM (Document Object Model) does natively. A screen reader can therefore still read a LaTeX PDF’s content in the wrong order or miss its structure, even when every caption and alt text is present. The HTML output from the same source is more reliably accessible without further work.
23.7.5 Exercises
- Render a short document with one
##and one####heading (no###between them) to HTML, then inspect the heading outline (in a browser, the accessibility or document-outline panel; from the shell,pandoc -t native report.qmd | grep Header). What does the skipped level look like from each view, and why is the second check necessary even though the page looks fine?
Visually, a #### heading typically renders smaller than the ## before it, so a sighted reader sees two headings of decreasing size and nothing wrong. The outline view shows the skip directly: a level-2 heading followed immediately by a level-4 heading, with no level 3 in between. A sighted reader has no reason to notice a level is missing, because font size, not level, is what they see. Checking the outline (or the Pandoc AST) catches the defect. It is invisible on the page, but it breaks navigation for a screen-reader user who jumps by heading level.
23.8 Float placement in PDF
A figure you cite in the prose can appear two pages later. LaTeX treats figures and tables as floats and moves them to avoid awkward white space and bad page breaks. For a paper, let it; readers expect floating figures. For a report meant to be read top to bottom, force placement where the figure is declared.
The fix in knitr Rmd:
```{r demographics, fig.cap = "Demographics", fig.pos = "H"}
plot(...)
```Or globally:
knitr::opts_chunk$set(fig.pos = "H")In Quarto, fig-pos is a figure option rather than an execution option, so it goes under the PDF format (or in a single chunk as #| fig-pos: "H"):
format:
pdf:
fig-pos: "H"H is from the float LaTeX package, meaning ‘place exactly here, do not float’. Add to the YAML:
header-includes:
- \usepackage{float}For tables, the equivalent is tbl-pos: 'H' in Quarto or kable_styling(latex_options = "HOLD_position") in knitr+kableExtra. Table 23.7 lists the placement codes.
htbp, lets LaTeX choose among the first four in that order.
| Code | Meaning |
|---|---|
h |
Here, if possible |
t |
Top of a page |
b |
Bottom of a page |
p |
On a separate page of floats |
! |
Prefix: override LaTeX’s usual limits on float placement |
H |
Exactly here, never float (requires the float package) |
For HTML output, float placement is irrelevant; figures appear in source order.
Question. You write ‘Figure 3 shows demographics’ and the rendered PDF puts Figure 3 four pages later. Why, and what is the fix?
Answer. LaTeX defers floats when placing them at the source location would create awkward white space or break a paragraph, sometimes by pages. There are two fixes, and they are best combined. Use fig-pos: "H" (with \usepackage{float} in the header) to force exactly-here placement, for documents that must be read linearly. And refer to the figure by its cross-reference (see @fig-demographics) rather than by a typed ‘Figure 3’, so that the number and the link are correct wherever the figure lands.
23.8.1 Exercises
- In a Quarto PDF with three tables, make every table appear exactly where it is declared.
Set the option once for the format and load the package:
format:
pdf:
tbl-pos: "H"
header-includes:
- \usepackage{float}Verify in the PDF that each table follows the paragraph that precedes it in the source. A table that still floats was probably produced by a package that writes its own LaTeX float environment (for example kableExtra), which needs that package’s option (latex_options = "HOLD_position") instead.
23.9 Troubleshooting a render
A render fails in one of two ways. The loud failure stops it with an error and a message that names the chunk; the silent failure finishes, exits successfully, and leaves a defect in the output. Table 23.8 collects the common ones; the worked example after it shows how to read a real log.
| Symptom (message excerpt) | Cause | Fix |
|---|---|---|
Error: ! object 'x' not found, then Quitting from doc.qmd:14-18 [label]
|
The object is created in a chunk that did not run (eval: false, or deleted) or runs later |
Read the Quitting from line for the failing chunk; make the defining chunk run, and run before it |
could not find function |
A package is used but not loaded in the document | Add the library() call to the document’s setup chunk; the render runs in a fresh session |
Unable to resolve crossref @fig-x (a warning), and ?@fig-x in the output |
A missing or misspelled label, a label without its fig- or tbl- prefix, or a chunk that did not run |
Fix the label; grep the output for ?@ (Section G.3) |
\@ref(fig:x) printed literally in the output |
A bookdown reference left unconverted |
Rewrite as @fig-x (Table G.1) |
No TeX installation was detected |
PDF output needs LaTeX | quarto install tinytex |
LaTeX Error: File ... .sty not found |
A LaTeX package missing from a minimal TeX installation | Install it (tinytex::tlmgr_install("float"), with the package’s name), or let TinyTeX install it on the next render |
ModuleNotFoundError in a Python chunk |
Python packages not declared |
reticulate::py_require() (Section G.4) |
unknown writer or an unknown format |
A misspelled format: name, or a Quarto older than the format |
Check the name; run quarto check and update Quarto |
| Figures pages away from their citation | LaTeX float placement |
fig-pos (Section 23.8) |
| Every render slow | Expensive chunks re-run every time |
freeze or cache (Section 23.3) |
| Old numbers after new data |
freeze or cache served stored results |
Render the document itself (Section 23.3) |
23.9.1 Worked example: a render that fails, then succeeds wrongly
The example renders a one-figure HF-HOME report, from the trial table of Section 23.4, in a temporary directory, with two defects planted from real conversions: a setup chunk left at eval: false from drafting, and a figure label that kept its R Markdown name. It runs the real quarto command, so the log below is what you would see.3
3 As in the earlier worked example, the env argument passes this session’s library paths to the R process that Quarto starts. In a terminal you would type quarto render report.qmd alone.
dbg <- file.path(tempdir(), "debug")
unlink(dbg, recursive = TRUE)
dir.create(dbg)
write.csv(trial[c("patient_id", "arm", "event_30d")],
file.path(dbg, "trial.csv"), row.names = FALSE)
doc <- c(
"---", "title: 'HF-HOME: primary outcome'", "format: gfm", "---",
"",
"```{r}",
"#| label: setup",
"#| eval: false",
"d <- read.csv('trial.csv')",
"obs <- d[!is.na(d$event_30d), ]",
"risk <- 100 * tapply(obs$event_30d, obs$arm, mean)",
"```",
"",
"@fig-risk shows the observed risk in each arm.",
"",
"```{r}",
"#| label: risk",
"#| fig-cap: 'Observed 30-day risk by arm'",
"barplot(risk, ylab = 'Risk (%)')",
"```"
)
render_doc <- function(doc) {
writeLines(doc, file.path(dbg, "report.qmd"))
r_libs <- paste0("R_LIBS=",
paste(.libPaths(), collapse = .Platform$path.sep))
log <- suppressWarnings(system2(
"quarto", c("render", file.path(dbg, "report.qmd")),
stdout = TRUE, stderr = TRUE, env = r_libs
))
status <- if (is.null(attr(log, "status"))) 0 else attr(log, "status")
log <- gsub("\033\\[[0-9;]*m", "", log)
log <- sub("^WARNING \\(.*\\) ", "WARNING ", log)
list(status = status,
log = grep("Error|^!|Quitting|WARN", log, value = TRUE))
}Render it:
first <- render_doc(doc)
first
#> $status
#> [1] 1
#>
#> $log
#> [1] "Error:"
#> [2] "! object 'risk' not found"
#> [3] "Quitting from report.qmd:16-20 [risk]"
#> [4] "WARN: Error encountered when rendering files"The render failed (a non-zero status), and the log says why in two lines. Read it from the bottom up. Quitting from names the file, the source lines, and the label of the chunk that failed, here risk. The error above it names what that chunk could not find. The object is defined in setup, which never ran. The fix is to let it run:
doc <- doc[doc != "#| eval: false"]
second <- render_doc(doc)
second
#> $status
#> [1] 0
#>
#> $log
#> [1] "WARNING Unable to resolve crossref @fig-risk"The status is now zero, and a build script or continuous integration would report success. The log still carries a warning. risk is not a figure label, because it lacks the fig- prefix, so the reference in the prose resolved to nothing. Look at the sentence Quarto wrote:
This is the silent failure, and it is the more expensive of the two. The first defect stopped the render. This one produced a finished document with the defect inside it. Rename the label:
doc <- sub("#| label: risk", "#| label: fig-risk", doc, fixed = TRUE)
third <- render_doc(doc)
third
#> $status
#> [1] 0
#>
#> $log
#> character(0)A render is done when the status is zero, the log has no warning, and the output contains no unresolved reference.
The first two conditions are the log; the third is the output, and it is the one that would have caught a converted paper sent to co-authors with ?@fig-flow in its methods section (Section G.1).
When a failure is not in Table 23.8, reduce it. Copy the document, delete chunks and prose until the error disappears, and restore the last thing you deleted. What remains is a minimal example, usually under twenty lines. It either shows you the cause or is ready to post to the Quarto discussion forum. quarto check reports the versions of Quarto, R, knitr, and LaTeX that belong in any such post.
A model is good at reading a render log, provided you give it the right excerpt and forbid the fixes that hide the error.
Context. A Quarto document fails to render. Below are the last 30 lines of the log, the chunk named in the
Quitting fromline with the chunks before it that define its inputs, and the output ofquarto check.Constraints. Do not suggest
error: true,eval: false,warning: false,try(), or reinstalling Quarto or R unless the log shows a version problem. Change as few lines as possible.Criteria. Name the line that fails and the cause, and say what the log shows that supports the diagnosis. After your fix, the render exits with status zero, the log has no
WARNline, and the output contains no?@.
Failure mode. The suggested fix silences the symptom, by skipping the chunk or tolerating the error, and turns a loud failure into a silent one. Check. Apply the fix, re-render, and run this section’s Verification on the output. A log and chunk code are structure; if the error message prints data values, cut them before sending (Section 12.3).
Question. In the debugging example, the second render exited with status zero. Why is a zero status not enough to call a render correct, and what two further checks does the Verification add?
Answer. A zero status means the document compiled. Quarto treats an unresolved cross-reference as a warning, so a document can reach a reader with ?@fig-risk in its prose and a successful build behind it. The Verification also requires a log with no warning and an output with no ?@.
23.9.2 Exercises
- A render log ends with these lines. Which chunk failed, what is the likely cause, and where do you look first?
4/9 [fit-model]
Error:
! object 'analysis_set' not found
Quitting from paper.qmd:61-70 [fit-model]
The chunk labeled fit-model, at lines 61 to 70 of paper.qmd, uses analysis_set before anything has created it. Look first at the chunk that should define analysis_set: it is set to eval: false, it comes after fit-model, or it was deleted. If the document reads analysis_set from a file or a pipeline target, check that the reading chunk ran.
23.10 Rules of thumb
- Habit 10: every number in the prose is computed. Sample sizes, estimates, intervals, and p-values are inline expressions, and figures and tables are cross-referenced by label.
-
Habit 8: a stale number is a plausible number, and a clean render is not a correct render.
freezeandcachewatch code, not data; after a data change, render the document itself and check the counts it reports. A zero exit status means the document compiled; grep the output for?@as well. -
Habit 2: the rendered document is a build product. Never edit the
.html,.pdf, or.docx; change the source and render again.
23.11 Cumulative practice
-
Cumulative (uses Chapter 18). Rebuild the worked example’s
trialtable withdplyr::left_join(), declaring the relationship and refusing unmatched keys, and assert that it has one row per randomized patient. Explain why the report’s first number depends on this join being right. - On your own work (no key). Replace every typed number in a draft of yours with inline code. Render it, render it again against deliberately different data, and confirm that every number changed.
library(dplyr)
trial_joined <- randomization |>
select(patient_id, site, rand_date, arm) |>
left_join(select(outcomes, patient_id, event_30d),
by = "patient_id",
relationship = "one-to-one", unmatched = "error")
stopifnot(nrow(trial_joined) == nrow(randomization),
identical(sort(trial_joined$patient_id),
sort(trial$patient_id)))
nrow(trial_joined)
#> [1] 2432The report’s first sentence counts the rows of trial.csv. A join that dropped patients would shrink the denominator, and one that multiplied them would inflate it. In either case the sentence would go on rendering a plausible number. Declaring the relationship and the unmatched behavior makes either failure stop the build.
23.12 Cheat sheet
| Task | Code | Guards against |
|---|---|---|
| Render a document | quarto render report.qmd |
A stale output (always executes) |
| Render a project | quarto render |
Inconsistent pages (respects freeze) |
| Put a number in a sentence | `{r} nrow(d)` |
Numbers typed from the console |
| Refer to a figure | @fig-label |
‘Figure 3’ pointing at the wrong figure |
| Cite a work | [@key] |
Hand-typed, unformattable references |
| Reuse a whole document’s results | execute: freeze: auto |
Re-running a slow analysis on every project render |
| Reuse one chunk’s result | cache: true |
Re-running one slow chunk |
| Re-run a cached chunk when data change | cache.extra: !expr tools::md5sum("data/x.csv") |
A cache that does not see the data |
| Render one variant | quarto render report.qmd -P site:"Site C" |
Five drifting copies of one report |
| Force a figure in place (PDF) |
fig-pos: "H" with \usepackage{float}
|
A figure pages away from its citation |
| Force a table in place (PDF) | tbl-pos: "H" |
A table pages away from its citation |
| Find unresolved references | grep -rn '?@' _book/ |
A clean render with broken references |
| Report versions for a bug report | quarto check |
A bug report no one can reproduce |
23.13 Further reading
- The Quarto documentation at
quarto.org, the canonical reference, in particular the guides to computations and to managing execution (freeze and cache). - (Wickham et al., 2023) Chapters 28 and 29, Quarto and its output formats.
- (Knuth, 1984), the paper that named the idea this chapter implements.
23.14 Prerequisites answers
- Literate programming (coined by Knuth) interleaves code with the prose that explains it, so the same source file is the authoritative record of both the computation and its interpretation. A Quarto
.qmdfile embodies this by letting you write narrative Markdown and executable R (or Python, Julia) code chunks in one document. The render process produces a human-readable artifact (HTML, PDF, Word) with code, output, and prose interleaved. -
quarto render file.qmdproduces the default output format declared in the document’s YAMLformat:key (HTML if noformat:is present). To force a format, usequarto render file.qmd --to html(or--to pdf,--to docx). - In a Quarto project,
execute: freeze: autostores each document’s executed results in_freeze/when the project is rendered. Later project renders reuse them for every document whose source is unchanged. They re-execute a document in full when any part of it changes. This avoids re-running expensive code on every render and makes CI deployments fast. It does not apply to a single-file render, which always executes, and the default isfreeze: false. Commit_freeze/to Git so collaborators benefit from it. - LaTeX treats figures and tables as floats and rearranges them by default to avoid bad page breaks.
fig-pos: 'H'(requires thefloatpackage) andtbl-pos: 'H'in Quarto YAML tell LaTeX ‘place this exactly here, no reflow’. The default placement,htbp, means ‘try here, then top, then bottom, then a float page’ in order.