15  Quarto (Revision Draft)

15.1 Proposed outline

  • I propose breaking out simple info into a “Quarto Basics” page for new users, and everything else into a “Advanced Quarto” page. Most reference material for you would go on the second page, hopefully making it easier to find.

  • I have eliminated console commands which require installing the quarto R package, as we are moving towards having students be comfortable with terminal from the start

  • All template links will need updating if we alter the organization in lab_support

15.2 Quarto Basics

This page is for those new to Quarto. It provides basic information on installing & writing simple Quarto scripts, in the same way you may have previously written an R script or R-Markdown script.

15.2.1 Installing Quarto

15.2.2 General Documentation

Comprehensive guide to Quarto

You can create a new quarto document from within RStudio using File -> New; or start by copying an existing script. We also have ?sec-Templates you can start with.

Quarto documents are styled primarily using Markdown. The Quarto Guide provides more detail on markdown basics

15.2.3 Documents

We use Quarto documents for two purposes - reproducible analyses and submitted papers. We will generally render analysis docs to html, and papers to pdf. The Quarto Guide provides more detail on on creating pdfs and html documents.

15.2.3.1 Output Formats

The YAML header of your quarto document specifies your output format. These pages provide additional format-specific header options:

15.2.4 Presentations

We also use Quarto to make revealjs slide decks for presentations. The Quarto Guide provides extensive documentation and sample slides.

Divs (:::) and spans([]) are used extensively in presentations. An introduction to their use is provided in the markdown basics chapter. The Pandoc manual provides more detail.

15.2.5 Chunk options

Chunk options are now specified inside the chunk rather than as part of the chunk header, with the following syntax:

#| echo: false
#| warning: false

To specify these options globally, they need to be added to the _quarto.yml file, with these lines:

execute:
   echo: false
   warning: false

15.2.6 Figures

To be included in the quarto figure environment, a code chunk producing a figure must have a label that starts with fig-. You can specify the caption as well as the output height/width (in inches) as follows:

```{r}
#| label: fig-1
#| fig-cap: "A Basic Barplot Figure"
#| fig-height: 6
#| fig-width: 6

ggplot(data, aes(x=name, y=value)) + 
  geom_bar(stat = "identity")
```

To display a code-generated figure without the caption, the label CANNOT start with fig-.You must also remove the #| fig-cap: option from the chunk, and explicitly include a height and/or width specification, this time using out-width and out-height:

```{r}
#| label: a-fig-1
#| out-width: 6in
#| out-height: 6in

ggplot(data, aes(x=name, y=value)) + 
  geom_bar(stat = "identity")
```

15.2.7 Simple HTML Tables

Plain knitr::kable() renders a nicely striped table in HTML:

Make Model Miles Per Gallon Cylinders Gears
Mazda RX4 21.0 6 4
Mazda RX4 21.0 6 4
Datsun 710 22.8 4 4
Hornet 4 21.4 6 3
Hornet Sportabout 18.7 8 3

See the Advanced Quarto page for code to produce more complex tables.

15.2.8 Citations

The Quarto Guide provides more detail about how to work with citations and footnotes. As with markdown, the format is [@citekey1; @citekey2] — citations go inside square brackets and are separated by semicolons

15.2.9 Bibliographies

To add a bibliography with a citation style, add the following lines to the .qmd file YAML header (or to the _quarto.yml for Advanced Formats):

bibliography: references.bib
csl: name_of_csl_file.csl

Note, we will typically call our csl files from the official Citation Style Language Repo; which simply requires the URL of the raw file from github.

See Advanced Quarto: CSL Files for YAML code for our commonly used CSL files

The Quarto Guide provides more detail about how to work with citations and footnotes. As with markdown, the format is [@citekey1; @citekey2] — citations go inside square brackets and are separated by semicolons

15.2.10 Rendering

At the most basic, inside RStudio you can use the terminal command quarto render path/to/filename.qmd to render your output document.

You can also specify what format to render to, using the --to flag:

quarto render path/to/filename.qmd # renders all formats specified in YAML header quarto render path/to/filename.qmd --to pdf # renders only PDF format

15.3 Publishing

Rendering a quarto document produces an output file of a specified format, usually in the same folder as the parent .qmd document. To make that file available to others, we instead publish the documents.

You can publish documents, books, and presentations to a variety of places. The two primary types you will encounter and how to publish them, are described below:

15.3.1 Internal Analysis Documents

John maintains a Reports repo in which we publish study-related analysis documents which should be shared among lab members only (i.e., which may display sensitive data). They are “published” by copying the bash script in the root of that repo (render_report.sh) to your project directory and running from within your project. The script also places the output document in a folder structure organized by study or project, and commits it to the report repo. This allows any lab member with repo access to view the html report without needing to re-run the analysis file, and without making sensitive data public.

15.3.2 Presentations and Reproducible Analysis Documents

Our preferred location for presentations and documents which are intended to be shared outside the lab is Quarto Pub. This site is public and free. You can set up your own account, or there are two lab accounts; one for presentations and one for other documents. Sensitive information should not be published to Quarto Pub. Formal presentations by lab members to public audiences should be placed in the arcpubs repo.

To publish a presentation (or other Quarto doc) to Quarto Pub, you should first log in on your default browsers. You should next go to the Terminal tab in the RStudio IDE. Navigate to the folder that contains your presentation. Then type quarto publish quarto-pub. If this is the first time you are publishing at Quarto Pub on that computer, you will need to authorize it. Follow the prompts in the web browser and then in the terminal to complete the publication process. This authorization is saved in a file called _publish.yml, which will be accessed for future updates to the presentation.

See additional instructions in the Quarto guide if necessary.

15.4 Advanced Quarto

This page is intended for those already familiar with the Quarto basics. It primarily provides specific code examples and refernces for specialized tasks involving Quarto.

15.5 Terminal Commands Quick Reference

  • quarto publish quarto-pub to publish a presentation or document to Quarto Pub
  • quarto render filename.qmd --to pdf
  • quarto render filename.qmd --to html
  • quarto render docname.qmd -o outputname.html
  • quarto render docname.qmd -P pv1:1 -P pv2:5
  • /opt/quarto/"${QUARTO_VERSION}"/bin/quarto check to check installation details

To get information on options you can use with a terminal command, type quarto command_name help: e.g., quarto render help will list all flag options for the quarto render command.

15.6 Advanced Format Types

15.6.1 Books and Websites

Information on setting up a book: https://quarto.org/docs/books/

Information on setting up a website: https://quarto.org/docs/websites/

Information on setting up Github Pages to publish a book/website on commit: https://quarto.org/docs/publishing/github-pages.html#render-to-docs

The difference between a book and a website in quarto is the syntax in the _quarto.yml file. Books have chapters, websites have sections; there are also a few differences in the types of metadata options you can specify (for example, books have titles and authors, websites do not). The main visible difference in the published output is that book chapters are numbered, while website sections are not.

15.6.2 Publishing Books and Websites

We have chosen to use Github Pages to publish several of our books. See this link for detailed information on setting up your repo to have a Github Page and to use Github Actions to publish.

Basically, any commit which includes changed html files tells Github Actions to re-build the book. The publishing workflow therefore consists of a) rendering locally, and b) committing the newly-rendered documents via github desktop. It usually takes <2 minutes for Github Actions to build and deploy the updated pages.

15.6.3 Manuscript Projects

As of 2025 our preferred method for creating public reproducible analysis is to have a quarto project for each study.

A project allows you to connect a website, presentations (both slidesets and posters), and PDFs/word documents to a set of analysis notebooks (formerly our ana_.Rmd files). That way, code across all output formats can be updated simultaneously from a single location. Plots and charts can also be produced from these notebooks, which can them be used across multiple output document formats.

15.6.3.1 Setting up a manuscript project from scratch:

  1. Create study repo for project on github in John’s account (call it study_NAME)
  2. Add collaborators to the repo
  3. Clone the repo to your computer
  4. Create manuscript project files in the repo. In the terminal (in github folder above new repo) type quarto create project manuscript and then indicate the name of the repo folder when asked
  5. Add a gh-pages branch to the repo. Do this in terminal with these commands
    • git switch --orphan gh-pages
    • git commit --allow-empty -m "Initial commit on orphan branch"
    • git push -u origin gh-pages
  6. Set up github to publish website from the gh-pages branch. Go to settings, pages, and select the gh-pages and /root as the branch to publish from. The website will be published at https://jjcurtin.github.io/study_NAME

15.6.3.2 Using the Study Template Repo

John has an existing repo which can be cloned to use as a template for a manuscript project. This will be more useful to our lab members than creating it from scratch, as it already has many useful modifications to the default project.

Note that in a project, presentations are located in subfolder that starts with an underscore, ie. _presentations, to prevent those files from being rendered during the project render.

15.6.4 Journal Articles

15.6.4.1 Manuscript Templates

Quarto does have a system for applying journal article templates to quarto docs, see this reference page

The list of available templates is still somewhat small, but extending them seems doable.

15.6.4.2 Generic Preprint template

15.6.4.3 AJP templates

15.6.4.3.1 APA templates
  • More APA style templates
  • Lab APA template. This is based on the template at this repo. Our version loads assets from our lab_support repo rather than installing the extention files locally. This is not a currently preferred template.
  • Typst APAish manuscript. As of 2025 this is our preferred APA manuscript format and is built into our template Manuscript Project.

Note that Typst manuscripts have a the built-in typst citation style, which takes a slightly different format than our usual YAML:

bibliography: references.bib
bibliographystyle: apa

Or you can download a local copy of the desired .csl file and call them that way:

bibliography: references.bib
bibliographystyle: name_of_csl_file.csl

As of summer 2025, this extension doesn’t support linking to the CSL repo (see Quarto Basics - Bibliographies).

15.6.4.4 CSL YAML Templates

Below are the YAML code of a couple that we use frequently (linked to the primary CSL repo)

NIH Grant Proposals:
csl: https://raw.githubusercontent.com/citation-style-language/styles/master/national-library-of-medicine-grant-proposals.csl

Elsevier (Vancouver substyle):
csl: https://raw.githubusercontent.com/citation-style-language/styles-distribution/f8524f9b9df60e94e98f824f242a1fb27cc9fc59/elsevier-vancouver.csl

APA 7th Edition:
csl: https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl

15.7 Other Lab Quarto Templates

All of the following templates are .qmd files for use in creating lab-related documentation tailored to ARC standards with respect to margins, font, etc:

15.7.1 Simple

Simple Quarto Template. This simple template allows you to set margins/font and to switch from HTML to PDF output.

15.7.2 Simple PDF

Simple PDF YAML Template. Simple template with YAML optimized for PDF output.

15.7.3 Simple HTML

Simple HTML YAML Template SUSAN ADD THIS

15.7.4 Simple R Analysis

Simple R Analyses HTML Template. Basic analysis script which invokes some of our paths and support functions. YAML optimized for HTML output.

15.7.5 Demo Slide Presentation

Demo slides. A presentation template.

15.7.6 Letterhead

UW Letterhead. Includes header images and signatures. See Susan if you plan to use this frequently enough that you’d like you name & sig embedded.

15.8 Advanced Rendering

15.8.1 Full book/website rendering

For books and websites, which have many .qmd documents linked together, you would render the full book by simply calling quarto render (with no arguments) to render all documents in the active project directory.

For books and websites, if anything changes in the .yml file (such as addition or deletion of a chapter), you MUST re-render the entire directory in this manner, otherwise the added/deleted chapter will not be rendered correctly.

15.8.2 Rendering multiple formats from a single .qmd script

For rendering books and slides separately, we have written a bash script to handle setting the _quarto.yml file and then rendering the full project or a single file.

  • call the function from the terminal: ./render.sh filename.qmd book
  • the first parameter can be the name of the qmd file or all to render all units (only used for books, not slides)
  • the second parameter can be book, slides or slides_wide (the latter is primarily for rendering on giant monitors)

15.8.3 Rendering other formats and targets

You can specify render targets and document render ordering more specifically in project metadata, see https://quarto.org/docs/projects/quarto-projects.html#render-targets

You can then call a specific format, e.g., PDF, with the --to flag: quarto render --to pdf. Only that specified format will be rendered.

Other specific rendering resources:

15.9 Using Parameters

You define parameters in the YAML using the syntax below

  • You can assign initial values to the parameters. These values will be used by default if you do not replace them with new values from the command line when you render the script.
  • You can update these values with new values you pass in when you render the script (see below).
  • If you only provide a subset of updated parameter values when you render the document, the default values will be used for the remaining parameters.
params:
  pv1: 5
  pv2: 10

In some instances, I prefer to assign the values from the params list to individual variables

  • Code is shorter when using these variables
  • I can update them interactively if I want to use different values (the params list is read-only)

First set the parameters in the YAML as above. Then put this code chunk right at the top of the script. If you edit this code chunk to assign new values interactively, make sure you comment it out when you save the final script!

pv1 <- params$pv1
pv2 <- params$pv2
# pv1 <- 5 # Use this line to interactively assign new value
# pv2 <- 10 # use this line to interactively assign new value

15.9.1 Using parameter values

When you use params in the YAML, a list named params is created.

  • You can then use this list as normal with no further code needed to establish the values.
params$pv1 + params$pv2
  • You can also access these values using inline r statements. See example below. I strongly recommend using this in the title of your document so that you can confirm that you correctly updated the parameter values when you rendered! e.g.,
title: "Demo of quarto document with pv1 = `r params$pv1` and  pv2 = `r params$pv2`."
  • Or if you assigned the parameter values to variables as I recommended, you can just use those variables as you normally would. They will start with the values assigned to associated parameters (in YAML or input from command line)

15.9.2 Passing parameter values at command line

I prefer to render quarto documents in the terminal.

  • You can indicate the output filename (otherwise, the output file name is set to the input filename with a different extension).
  • You can also pass in values to the parameters, which is typically why we use parameters in the first place

Use the following syntax to render quarto documents at command line.

  • use -P to provide a parameter value. No space between parameter name and value. If you provide values for only a subset of parameters, defaults will be used for other parameters
  • use -o to specify filename (defaults to input filename if not provided).
quarto render docname.qmd -o outputname.html  -P pv1:1 -P pv2:5

15.10 Advanced Tables

15.10.1 HTML Tables

If you use the kableExtra page, you will find it does away with the nice striping and spacing from plain kable(), and you then have to define that explicitly.

Make Model Miles Per Gallon Cylinders Gears
Mazda RX4 21.0 6 4
Mazda RX4 21.0 6 4
Datsun 710 22.8 4 4
Hornet 4 21.4 6 3
Hornet Sportabout 18.7 8 3

Note the table above, although the code is identical to the table displayed in the Basic Quarto section, has lost all formatting thanks to invoking kableExtra. The table below reproduces that formatting via kable_styling (with additional features such as floating around text, and footnotes; although it seems the float doesn’t actually work!).

Make Model Miles Per Gallon Cylinders Gears
Mazda RX4 21.0 6 4
Mazda RX4 21.0 6 4
Datsun 710 22.8 4 4
Hornet 4 21.4 6 3
Hornet Sportabout 18.7 8 3
Note:
Here is a general comments of the table.
1 Footnote 1;
2 Footnote 2;
a Footnote A;
b Footnote B;
* Footnote Symbol 1;
† Footnote Symbol 2

Additional HTML-only features of kableExtra are documented here

15.10.2 PDF/LaTeX Tables

If using the typst APAish manuscript extension, note that Quarto 1.4XXX uses an older version of Typst without good table support. That should be fixed in the 1.5 release. (Summer 2025: still not fixed)

The documentation for producing LaTeX tables in kableExtra is here

The following two tables demonstrate a complex table of the type used in the PDF ema and burden papers (here replicated with a far simpler dataset). This first table is the table code as extracted directly from the manuscript, with no additional formatting. It displays not unlike an HTML table:

Iris
N %
Setosa
large NA NA
small 50 0.3
Versicolor
large 43 0.3
small 7 0.0
Virginica
large 50 0.3
small NA NA
Note:
N = 75

In LaTeX, this table displays quite differently. Below, the same code has been modified to reproduce exactly the look of the table as it appears in the PDF manuscript. That is, the code in the chunk above produces the output below when rendered with knitr to PDF; but rendering that output to HTML requires the additions in the chunk below:

  • bootstrap_options = "none" added to kable_styling removes the default horizontal lines, under each row, but then font size and table width must now be specified.
  • pack_rows() adds horizontal lines in HTML but not LaTeX; those must be removed with the label_row_css option .
  • Finally, column width is specified, and horizontal lines around the column headers and before the footnote, are added with row_spec()’s extra_css option.
Iris
N %
Setosa
large
small 50 0.3
Versicolor
large 43 0.3
small 7 0.0
Virginica
large 50 0.3
small
Note:
N = 75

15.10.3 Useful Table Options and features

To be sure tables display with NA cells as blanks (instead of “NA”) include this before your first table:

options(knitr.kable.NA = "")

kableExtra has a useful function called collapse_rows, yet that seems to be persistently broken (Summer 2025: Ostensibly fixed)

row_spec() has a parameter, hline_after, which, ostensibly, should create a horizontal line under that row, right? Apparently it only works on LaTeX although this is undocumented. Apparently the solution is to add row_spec(X, extra_css = "border-bottom: 1px solid")) (where x is the rownum; 0 for the header, nrow(df) for the last row)

Similarly, to supress hlines on headers created by pack_rows(), you need to add extra_css = "border-bottom: none" into the pack_rows() command.

15.11 Advanced PDF formatting using LaTeX

Formatting of a PDF rendered from Quarto can be finely controlled with the addition of LaTeX commands. See this Quarto reference as well as some examples below:

15.11.1 PDF Fonts

To specify a font you add the following to the YAML:

If using Xelatex:
mainfont : FontName # for document text
sansfont : FontName # for H1-H6 text
monofont : FontName # for code chunk text

If using pdflatex:
fontfamily : FontName # for document text

Where FontName is the name of your desired system font. To find available system fonts, run, systemfonts::system_fonts() and look for the name of the font (not the name of the font .tff file). For example, if you wish to use Arial font, your FontName should be “ArialMT”, rather than “arial” or “Arial”.

15.11.2 Inline Commands

Certain LaTeX commands can be placed in qmd files as plaintext (on their own line, with surrounding blank lines), for example: \newpage starts a new page, \hline adds a horizontal line.

15.11.3 Chunk Commands

Multiline commands can be wrapped in LaTeX code chunks:

15.11.4 LaTeX YAML Commands

\raggedright added to the include-in-header YAML command, ensures lines are flush with the left margin and ragged on the right margin (vs justified where text is stretched to ensure both margins are flush)

We use the following in the YAML header to set up a html document to render as a single file with a TOC.

format: 
  html: 
    embed-resources: true
    toc: true 
    toc_depth: 4

15.11.5 LaTeX Packages

  • \usepackage{wrapfig} - allow text wrapping
  • \usepackage{float} - allow use of float options such as H (use UPPERCASE to preserve floats)
  • \usepackage{caption} - allows supression of automatic caption numbering
  • \usepackage{lscape} - allows insertion of a landscape oriented page
  • \usepackage{enumitem} - allows fine-grain control over list styling