14  Quarto

14.1 General

14.1.1 YAML formats

14.1.2 CLI Rendering

  • quarto render filename.qmd –to pdf
  • quarto render filename.qmd –to html

Comprehensive guide to Quarto

14.1.3 Chunk options

Chunk options are now specified inside the r backtics, 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

14.1.4 Figures

To be included in the quarto figure environment, 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")
```

14.1.5 Tables

14.1.5.1 HTML

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

However, when you call kableExtra, it does away with the nice striping and spacing 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 first table, has lost all formatting thanks to invoking kableExtra. The table below re-produces that 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

14.1.5.2 PDF

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.

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

14.1.5.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 function is collapse_rows, yet that seems to be persistently broken

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.

14.1.6 Rendering

14.1.6.1 Single-page rendering

Hitting the Render button renders the single active document. This will be the primary method of rendering for analysis documents, manuscripts, and presentations.

This method can also be used to re-render a single chapter in a book or a single page on a website.

14.1.6.2 Full book/website rendering

For books and websites, which have many .qmd documents linked together, you would render the full book by calling quarto::quarto_render() 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.

14.1.6.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

14.1.6.4 PDF

You can specify rendering to PDF format by adding the following to your .yml file:

format: pdf: documentclass: book

You can then explictly render just the PDF format by specifying both the output format and the filename in the call to quarto_render:

quarto::quarto_render(output_format = “pdf”,output_file = “dwt.pdf”)

14.1.6.4.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”.

14.2 Documents

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

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

14.3 Journal Articles

14.3.1 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.

Related reference links for creating an AJP template:

14.3.2 Bibliographies

To add a bibliography with a citation style, add the following lines to the _quarto.yml or the .qmd file:

bibliography: references.bib
csl: name_of_csl_file.csl

For a typst APAish manuscript your yaml will look like this to use the built-in typst citation style:

bibliography: references.bib
bibliographystyle: apa

Or download a local copy of the desired .csl file:
bibliography: references.bib
bibliographystyle: name_of_csl_file.csl

At the moment, this extension doesn’t support linking to the CSL repo (below).

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 docs_arc for specifics about commonly-used ARC 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

14.4 Reproducible Analyses

14.5 Presentations

We use Quarto to make revealjs slide decks for presentations. The Quarto Guide provides extensive documentation and sample slides. You can begin with the overview of presentations across formats (Quarto can also render powerpoint and other formats). Follow this with a revealjs overview and then the revealjs reference chapter. The Quarto Guide also provides a chapter on presenter tools.

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.

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

14.6 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.

14.7 Publishing

You can publish documents, books, and presentations to a variety of places.

14.7.1 Presentations and Documents

Our preferred location for presentations (and Quarto Docs) is Quarto Pub. This site is public and free. To use it, you need to set up an account first.

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.

14.7.2 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

14.8 Terminal Commands

  • quarto publish quarto-pub to publish a presentation or document to Quarto Pub

14.9 Latex and Quarto

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:

14.9.1 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.

14.9.2 Chunk Commands

Multiline commands can be wrapped in latex code chunks:

14.9.3 YAML Commands

\raggedright added to the inclde-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)

14.9.4 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

14.9.5 Re-render and freeze

https://quarto.org/docs/projects/code-execution.html