Intro to Quarto

The Next Evolution of R Markdown for Literate Programming and Communication

Richard Ressler

1/22/23

Summary

Quarto is a new open-source scientific and technical publishing system from Posit.

Quarto users can:

  • Create multi-language projects with R, Python, Julia, Observable, … (R not required)
  • Use one document to create reports, journal articles, presentations, web content,… in HTML, PDF, Word, PowerPoint, … All Formats
  • Write/code in multiple tools such as RStudio, JupyterLab, VS Code, Text Editors, …
  • Use .Rmd files or python .ipynb, or “upgrade” to .qmd for more features …
  • Collaborate across teams using different formats, languages, and tools.

Quarto has a shallow learning curve, especially for R Markdown users.

  • It’s the next-generation of R Markdown and Posit’s focus for new capabilities.
  • Comes “batteries included” so no need to manage multiple packages.
  • Extensive on-line documentation, an active community, and numerous videos and blogs, e.g. A Quarto tip a day .
  • Multiple themes with options for customized CSS/SCSS, or \(\LaTeX\).

A great capability for literate programming and communicating your work!

Quarto Unifies and Extends the R Markdown Ecosystem

Quarto Builds on the History of Literate Programming

1984: Donald Knuth introduces the concept of Literate Programming to improve the development of computer-programs by describing the logic in text followed by the code.

“Programming is the art of telling another human being what one wants the computer to do.” Donald E. Knuth

Donald Knuth\'s book Literate Programming

2004: Markdown language enables people to create “easy-to-read and easy-to-write” plain text in a .md file that could be converted to HTML or XML output.

2006: Pandoc enables users to convert a markdown .md file (and many other types) to multiple output formats.

2012: R Markdown and the {knitr} package (based on Sweave) enables R users to more easily mix documentation and source code.

knitr package hex sticker rmarkdown package hex sticker

Numerous Packages are developed to extend R Markdown

blogdown package hex sticker bookdown package hex sticker pagedown package hex sticker rticles package hex sticker xaringan package hex sticker

2022: Posit releases Quarto as an open source scientific and technical publishing system built on Pandoc.

Quarto hex sticker

Quarto Unifies the R Markdown Ecosystem

Quarto incorporates capabilities of multiple packages to allow for diverse outputs:

  • Documents: HTML, PDF, Word
  • Websites
  • Blogs
  • Web-Books
  • Presentations:
-   HTML (Revealjs)
-   PDF (Beamer)
-   PowerPoint (.pptx)

Quarto tries to create consistency across formats but HTML can be interactive and PDF cannot.

Quarto supports multiple languages: R, Python, Julia, Observable, …

  • Can use either Knitr or Jupyter computation engines (R is NOT required)
  • Can support R and Python in the same file with R {reticulate} package.

Quarto operates as a Command Line Interface in the Terminal window and …

  • Is integrated into RStudio (v2022.07+) and works in JupyterLab , VS Code, Text Editors.
  • Can render python .ipynb

Quarto supports \(\LaTeX\) and math with MathJax (including AMSmath)

Quarto Extends R Markdown

Quarto creates plain-text files using YAML and R Markdown tags.

Quarto works with .Rmd files but recommends upgrading for more features.

  • Quarto files end in .qmd instead of .Rmd.
  • Use a slightly different YAML Syntax to make it easier to change outputs and be consistent across languages and tools.
    • format: html instead of output: html_document.
  • Use #| option: value for chunk options instead of fitting into the chunk header.
  • You can edit to convert the chunk options or use knitr::convert_chunk_header().
    • knitr::convert_chunk_header("your.Rmd", "your.qmd", type = "yaml")

R Markdown Chunk Options

```{r mtcars, eval=FALSE}
nrow(mtcars)
```

Quarto Chunk Options as #|

```{r}
#| label: mtcars2
#| eval: false
nrow(mtcars)
```

Quarto Does Not Need R to “Render” non-R Output

R Markdown knitr process

R Markdown starts with a .Rmd file and calls the R package Knitr to perform the computations and convert the output to a .md file. It then uses Pandoc to convert to various file formats.

Quarto_render process

Quarto scans the file and chooses either the Knitr or Jupyter engine to perform the computations and converts it to a .md file. It then uses Pandoc to convert to various file formats.

Working with Quarto

Getting Started with Quarto in RStudio

Quarto is fully integrated into RStudio (V2022.07 +)

  • Create new documents
  • Auto-complete for yaml and chunk options
  • Operate using the IDE or use the console command line

Open an existing .Rmd file or edit an existing .qmd file as usual.

To create a new file you can use the menu for File/New File/Quarto Document.

You can add many options to your YAML and see the auto complete in action.

---
title: "Untitled"
format: html
editor: visual
date: today
theme: cerulean  # lots of options for themes
number-sections: true # automated numbering of headings
self-contained: true # For HTML to allow sharing of complete files (makes them larger)
code-fold: true # collapse code chunks with option to show the code
execute:        # set global code chunk options as in Rmarkdown Setup chunk
  echo: true
  eval: true
  freeze: true  # New capability to save calculations to speed later renders
---

Quarto has an Expanded Visual Editor in RStudio

The RStudio Visual Editor provides a WYSIWYM capability.

  • It shows what you “mean” but does not completely render all the elements on the page.
  • You can preview the rendered version in either the Viewer or Presentations Panes or switch to a Window view in a browser using the

The Visual Editor provides access to many formatting options and special features through the Format and Insert menus.

I often go back and forth between the Visual Editor and the Source Editor as I find it much easier to “fix” things in the Source Editor.

The Visual Editor is great for inserting features such as tab panels, columns, callout blocks, or span formatting and then going to the Source Editor to fine tune them.

Tables are still limited in R Markdown but the Visual Editor makes it much easier to create and edit large tables.

The Visual Editor will “Escape” errors with /

If you edit something in source, such as a table or math and try to see it in the visual editor, Quarto will “escape” all special characters such as [ or | with a \ so you have a lot to clean up manually. Using the IDE Find and Replace can help.

Writing Math and \(\LaTeX\) in Quarto

Quarto supports \(\LaTeX\) for writing math equations (\(\text{Area} = \pi r^2\)), matrices, as well as numbering and cross-references using {#eq-my-equation}.

\[ \begin{align} \hat{\beta}_1 & = \frac{\sum(x_i - \bar{x})(y_i - \bar{y})}{\sum(x_i - \bar{x})^2} \\ \hat{\beta}_0 & = \bar{y} - \hat{\beta}_1x \end{align} \tag{1}\]

\[ A = \begin{bmatrix}a_{11}&a_{12}&\cdots &a_{1m} \\ \vdots & \vdots & \ddots & \vdots\\a_{n1}&a_{n2}&\cdots &a_{nm}\end{bmatrix} \]

\[ m_{ij} = (a_{i1}b_{1j} + a_{i2}b_{2j} + \cdots + a_{im}b_{mj}) = \sum_{k=1}^{m} a_{ik}b_{kj} \tag{2}\]

Careful with Spacing

Both source and visual editor views will preview correct latex.

  • No space after leading $ or before trailing $ in inline mode.
  • You can put $$ on separate lines at times
  • If using a \(LaTeX\) environment, e.g.,\begin{array} you can skip the $$.

If copying and pasting latex code, be sure to paste into the Source editor otherwise all of your \ may get escaped as \\.

For revealjs presentation, adding html-math-method: mathjax to YAML avoids a formatting bug in mathjax for Chrome.

Divs and Spans

Quarto allows you to create a Div or a Span to customize sections of the document, or pieces of code.

A Div creates a block (division) of the document that gets special treatment.

  • Divs are used for many built-in features to include tab-sets and callout boxes.
  • You can customize a Div and nest Divs within other divs.
  • Use the Visual editor to Insert and or enter a pair of ::: to delineate the div.
  • The Div should be separated by blank lines from preceding and following blocks.

A Span is used for giving special treatment to a section (span) of text.

  • You can customize a Span using CSS and nest Spans within other Spans
  • Use the Visual editor to Format a span or delineate the text inside and add the attributes you want after it using [This is *some text*]{.class key="val"}.

I often use the Visual editor to insert a div or span, especially tabsets or callout boxes, and then switch to the Source editor to move content around.

Quarto Extensions

Quarto has an array of extensions that allow you to add additional capabilities to your document.

  • Extensions exist for Shortcodes/Filters, Journal Articles, Custom Formats, and Revealjs

Extensions must be installed for each Quarto project.

Consider the FontAwesome extension for including 2,000 free icons in either HTML or PDF.

  • Install using the terminal with quarto install extension quarto-ext/fontawesome.

  • This will create a directory _extensions/quarto-ext/fontawesome

  • Use shortcode {{< fa name >}} :

  • Users can adjust the size, color, and accessible text for the icons.

Scholarly Writing

Quarto has features to simplify formatting for publication on the web or in academic journals.

Cross References provide numbered references and hyperlinks to elements of your document that you choose.

Labels {#type-name} go after the element (separated by a space) or as an option in a code chunk, e.g., #| label: fig-plots

  • Common elements include Figures #fig-, Tables #tbl-, equations #eq-, Section Headings #sec-, and others
  • The name must be unique within the document (or across documents in a project)
  • Add crossref: chapters : true to the YAML to indicate that top-level headings (H1) in your document correspond to chapters, and cross-references should be sub-numbered by chapter.

Figures and tables, whether generated by markdown or in a code chunk, must have a Caption as well to be cross-referenced.

To reference a labeled item, use @type-name for the item of interest.

Quarto can support BibLaTeX (‘.bib’) or BibTeX (‘.bibtex’) files for Citations

  • Add the relative path to the file to the YAML, e.g., bibliography: references.bib
  • Recommend using Zotero with the Better Bibtex addin to manage your collection of citations.

Quarto uses the standard format [@citation-key where citations go inside square brackets and are separated by semicolons - The citation-key must be present in the referenced .bib file.

The default is the Chicago Manual of Style author-date format, but you can specify a custom format by adding csl: myformat.csl to the YAML where myformat is a file such as found at Zotero Style Repository

Quarto has Templates for several journals and Posit and the open source community are building more (and you can build your own as well).

For pre-built templates, use the terminal to install the extension, e.g., quarto install extension quarto-journals/jasa.

Then edit the YAML to use the template format, e.g., format: jasa-pdf

The pre-built templates usually have an example .qmd file with their options.

Customizing Quarto

Quarto has many options to customize your output for each type of format.

  • The quarto Gallery has lots of examples.

If one of the built in themes fonts, colors, sizes, layout does not suit your purpose, you can create your own variations.

  • for HTML: embed HTML tags or more generally, use a custom SCSS file to adjust existing CSS classes or add your own.
  • for PDF, you can use any option Pandoc allows for PDF Latex

You can change the page layout

  • Add columns using a div
  • Move content to the margins

You can choose different languages for the document.

Quarto Projects

Quarto Projects Overview

Quarto Projects are not the same as RStudio Projects.

A Quarto Project is a folder with (usually) multiple documents that should be rendered together under common options.

  • You can still override the common options though for portions of the project

Projects are used to create articles from multiple source documents, websites, books or other collaborative efforts.

Quarto projects are characterized by their use of a _quarto.yml file which serves as a configuration file for the project.

  • Edit the _quarto.yml file to define the elements of the project and any common options you want to apply across the project.
  • Adding the The YAML freeze: auto option will keep track of all documents that have been rendered and only re-render a file when it has changed.

Use the RStudio File/New project command or run quarto create_project in the terminal in the directory where you want to create a project.

Personal Websites and Blogs

The {blogdown} package is an R Markdown based package for creating personal websites or blogs using Hugo.

Quarto streamlines creating a website/blog with many options for customizing and enhancing it over time.

The Quarto Guide Creating a Website shows how to create a website or a blog.

  • These are both Quarto Projects as you use multiple .qmd files for a website or blog.
  • A Website organizes your files based on the structure navigation you define in the _quarto.yaml , e.g. navigation bars of Tabs and/or Menus and/or a sidebar menu etc..
  • A Blog uses a listing page which will search for files under a directory and organize the files by date/time.

If you want a combination of website and blog, recommend creating a website and then in the navigation add a .qmd file with the line listing: default in the YAML header.

Quarto generates a standard structure of HTML files for all the contents of your website/blog.

Thus you can publish it in a wide variety of places for free.

Quarto has its own site, quarto.pub.com, where you can publish your work.

Once you set up an account, it is a two step process:

  1. Render your website in RStudio (this is where the freeze: auto speeds things up).
  2. Publish your website using the command quarto publish in the terminal window in the project directory.

You can add new files and update your website as often as you wish.

Listing 1: _quarto.yml

    project:
      type: website
    website:
      title: "Richard Ressler's Data Science Site"
      navbar:
        left:
          - text: "Home"
            file: index.qmd
          - text: "Data Sets"
            file: data_sets/data_sets.qmd
          - text: "Blog"
            file: posts/posts.qmd
          - text: "Talks"
            file: talks/talks.qmd
    execute:
      freeze: false # re-render only when source changes
    format:
      html:
        theme:
          light: flatly
          dark: darkly
        css: styles.css
        toc: true
    editor: visual

Website Directory Structure

Closing Summary

Quarto is the next generation of R Markdown and integrates capabilities from multiple packages for a more consistent approach to literate programming and scientific and technical publishing.

We just scratched the surface today of its capabilities right out of the box and how you can customize your work.

More developments are coming:

  • Add Track Changes/Comments in the visual editor for collaboration
  • Add HTML widgets
  • Add more templates for journals

Use Quarto for reproducible work at AU and beyond!

  • The online tutorials and documentation are great places to start!
  • See Awesome Quarto for a curated list of resources.
  • Try it out! Experiment! Review the Quarto Discussions or Ask for Assistance.
  • Create your Website or Blog and let everyone know what you are up to!

https://rressler.quarto.pub/intro-to-quarto/#/title-slide/