Quarto

Elevating R Markdown for Advanced Publishing

Christophe Dervieux

Posit PBC

July 9, 2024

What is Quarto?

An open-source, scientific and technical publishing system

Quarto is the next generation of R Markdown

• it unifies and improves the R Markdown ecosystem

• it extends it for people who don’t know R Markdown

Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.

Just like R Markdown you can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books and more.

• Consistent implementation of attractive and handy features across outputs: tabsets, code-folding, syntax highlighting, etc.
• More accessible defaults as well as better support for accessibility
• Guardrails, particularly helpful for new learners: YAML completion, informative syntax errors, etc.
• Support for other languages like Python, Julia, Observable, and more via Jupyter engine for executable code chunks.

Next in presentation -> broad overview of Quarto and its feature.

Why Quarto?

• Computational Documents and Scientific Markdown made easy for Single Source Publishing
• Designed from the start as multi-engine
• An attempt to bring +10 years experience of R Markdown to everyone!

 

D. Krishnamurthy, “Writing technical papers with Markdown and Pandoc,” Dec. 20, 2015. https://kdheepak.com/blog/writing-papers-with-markdown

Origins

• Open source project sponsored by Posit, PBC.
• 10 years of experience with R Markdown convinced us that the core ideas were sound.
• The number of languages and runtimes used for scientific discourse is very broad.
• Quarto is a ground-up re-imagining of R Markdown that is fundamentally multi-language and multi-engine.

Computational Documents

• Documents that incorporate the source code required for their production
• Notebook and plain text flavors
• Automation and reproducibility

How to use Quarto?

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into static PDF/Word/HTML reports, books, websites, presentations and more.

$ quarto --help

Usage:   quarto
Version: 1.5.53

Description:

  Quarto CLI

Options:

  -h, --help     - Show this help.
  -V, --version  - Show the version number for this program.

Commands:

  render     [input] [args...]     - Render files or projects to various document types.
  preview    [file] [args...]      - Render and preview a document or website project.
  serve      [input]               - Serve a Shiny interactive document.

  create     [type] [commands...]  - Create a Quarto project or extension

  use        <type> [target]       - Automate document or project setup tasks.
  add        <extension>           - Add an extension to this folder or project
  update     [target...]           - Updates an extension or global dependency.
  remove     [target...]           - Removes an extension.

  convert    <input>               - Convert documents to alternate representations.
  pandoc     [args...]             - Run the version of Pandoc embedded within Quarto.
  typst      [args...]             - Run the version of Typst embedded within Quarto.
  run        [script] [args...]    - Run a TypeScript, R, Python, or Lua script.
  install    [target...]           - Installs a global dependency (TinyTex or Chromium).
  uninstall  [tool]                - Removes an extension.

  tools                            - Display the status of Quarto installed dependencies
  publish    [provider] [path]     - Publish a document or project to a provider.
  check      [target]              - Verify correct functioning of Quarto installation.
  help       [command]             - Show this help or the help of a sub-command.

How to use Quarto?

Quarto integrates with other tools.

Quarto Workflow

• Same workflow logic than R Markdown: Engine + Convertion
• knitr / rmarkdown is used for R code cells then Pandoc for convertion.
• Quarto is tweaking several parts of those steps to bring Scientific markdown features, and great computational document experience
• Same for Jupyter

Quarto Syntax

From R Markdown…

---
title: Hello penguins!
output: 
  html_document:
    toc: true
---
  
Some **Markdown** content based on _Pandoc_'s markdown

```{r species, fig.width=5, fig.cap="About penguins"}
ggplot(penguins) + aes(x = bill_length_mm, y = bill_depth_mm, color = species) +
  geom_point() + labs(x = "Bill length (mm)", y = "Bill depth (mm)")
```

• Quarto syntax is very similar to R Markdown syntax with slight differences
• YAML header to set configuration for quarto
• Cell options to set configuration for engines

Quarto Syntax

… to Quarto

---
title: Hello penguins!
format: html
toc: true
---

Some **Markdown** content based on _Pandoc_'s markdown

```{r}
#| label: species
#| fig-width: 5
#| fig-cap: About penguins
ggplot(penguins) + aes(x = bill_length_mm, y = bill_depth_mm, color = species) +
  geom_point() + labs(x = "Bill length (mm)", y = "Bill depth (mm)")
```

• A different key for output format, which are no more R function. Closer to Pandoc default way of working, and so more compatible
• A different way to set options for code chunks, with a multiline syntax using in-YAML configurations.
  • Because it is a broader syntax for engines, and also more compatible with Pandoc own specification
• For R, Quarto still uses Knitr under the hood.
• Consequently, the vast majority of existing Rmd files can be rendered unmodified.

Quarto formats

Multiple fresh polished formats, built-in, with consistent syntax and features.

Feature	Quarto	R Markdown
Basic Formats	html pdf docx typst	html_document pdf_document word_document typst_document
Beamer	beamer	beamer_presentation
PowerPoint	pptx	powerpoint_presentation
HTML Slides	revealjs	xaringan ioslides revealjs

The R Markdown ecosystem was built over nearly a decade (resulting in lots of inconsistency & duplication)

Quarto formats

Multiple fresh polished formats, built-in, with consistent syntax and features.

Feature	Quarto	R Markdown
Cross References	Quarto Crossrefs	html_document2 pdf_document2 word_document2
Advanced Layout	Quarto Article Layout	tufte distill
Websites & Blogs	Quarto Websites Quarto Blogs	blogdown distill
Books	Quarto Books	bookdown
Interactivity	Quarto Interactive Documents	Shiny Documents
Dashboards	Quarto Dashboards	flexdashboard

Important : - Built-in Quarto - Some features requires specific R packages and specific syntax. - Fresh new format (HTML 5, boostrap 5, Typst for PDF, …)

Next, let’s focus on some of the features that make Quarto unique.

Focus: HTML Theming

Quarto theme files are based on SCSS for all HTML output formats (shared by HTML and RevealJS slides, extendable to work with anything).

For boostrap document, based on core variables defined by bslib (so fully compatible with Shiny, Flexdashboard, & R Markdown themes).

my-style.scss (Quarto theme file)

/*-- scss:defaults --*/
$h2-font-size:          1.6rem !default;
$headings-font-weight:  500 !default;

$custom-color: blue;

/*-- scss:rules --*/
h1, h2, h3, h4, h5, h6 {
  text-shadow: -1px -1px 0 rgba(0, 0, 0, .3);
  color: $custom-color;
}

_quarto.yml or YAML header

format:
  html:
    linkcolor: darkgrey
    theme: [litera, my-style.scss]

Focus: Typst CSS for nice table output in PDF

New PDF rendering through Typst (https://typst.app)

format: typst

This is the quickest way to do PDF with already nice features !

# Producing a HTML Table with CSS styles
library(gt)

temps <- data.frame(
  year = c(1920:1924),
  Jan = c(40.6, 44.2, 37.5, 41.8, 39.3),
  Jun = c(58.5, 58.7, 57.8, 52.7, 57.7)
)

nice_col <- scales::col_numeric(
  colorspace::diverge_hcl(
    n = 9, palette = "Green-Orange"
  ), domain = c(35, 62)
)

gt(temps) |> 
  data_color(
  columns = c(-year), 
  fn = nice_col
)

Rendered in PDF with Typst

HTML tables are parsed and rendered to output format, and style is kept in PDF with typst.

Focus: Publishing

Integrated quarto publish command that targets a variety of services

> quarto publish --help

Usage:   quarto publish [provider] [path]
Version: 1.5.52

Description:

  Publish a document or project to a provider.

  Available providers include:

   - Quarto Pub (quarto-pub)
   - GitHub Pages (gh-pages)
   - Posit Connect (connect)
   - Posit Cloud (posit-cloud)
   - Netlify (netlify)
   - Confluence (confluence)
   - Hugging Face Spaces (huggingface)

  Accounts are configured interactively during publishing.
  Manage/remove accounts with: quarto publish accounts

Focus: Shortcodes

Quarto specific syntax to include content: https://quarto.org/docs/authoring/shortcodes.html

Let's add some sample image ! 

![A caption]({{< placeholder >}})

placeholder is one of the built-in shortcodes

Let’s add some sample image !

A caption

Shortcodes is among what is extensible using Quarto Extensions

Quarto Projects

A Quarto Project is a directory that contains a file called _quarto.yml.

Organizing content as a project to gain project’s features and enhanced outputs

# from project root
quarto render

• Projects have a type (website, book, manuscript, …) driving behaviors and specific features
• Shared metadata from project to sub-folder level
• Reproducibility with computations can be controlled (cache, freeze)
• Pre and Post render scripts can be added
• Project Profile for distinct project behavior

Quarto Projects

Examples of project’s configurations

_quarto.yml (simple website)

project:
  type: website

website:
  title: "today"
  favicon: logo.png
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
    
freeze: auto

_quarto.yml (simple book)

project:
  type: book

book:
  title: "mybook"
  author: "Jane Doe"
  date: "8/18/2021"
  chapters:
    - index.qmd
    - intro.qmd
    - references.qmd

bibliography: references.bib

format:
  html: default
  pdf: default
  epub:
    cover-image: cover.png

Learning More

This presentation aimed to give you a taste of what Quarto can do and a broad overview of its features.

Follow other talks at useR! 2024 to learn more about Quarto, and our resources below.

Resources

• Getting started: https://quarto.org/docs/get-started/

• User guide: https://quarto.org/docs/guide/

• Awesome Quarto: https://github.com/mcanouil/awesome-quarto

Questions?