Chapter 6 Quarto

Quarto Guide (quick tutorial): https://quarto.org/docs/guide/

Quarto Reference (detailed documentation): https://quarto.org/docs/reference/

Quarto Tutorial: https://jmjung.quarto.pub/m02-advanced-literate-programming/#learning-outcomes

Run Quarto in VS Code: https://quarto.org/docs/tools/vscode/index.html

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. See the full documentation of Pandoc’s Markdown for more in-depth documentation.

Cell Execution

Quarto Command Keyboard Shortcut
Run Current Cell ⇧ + ⌘ + Enter
Run Current Cell and Jump to Next Cell ⇧ + Enter
Run Selected Line(s) ⌘ + Enter
Run All Cells ⌥ + ⌘ + R

Host Quarto on GitHub Pages.

To get started, change your project configuration _quarto.yml to use docs as the output-dir.

project:
  type: book
  output-dir: docs

Then, add a .nojekyll file to the root of your repository that tells GitHub Pages not to do additional processing of your published site using Jekyll (the GitHub default site generation tool):

touch .nojekyll
  • Note that .nojekyll’s location is different than that of bookdown, which is at /docs folder.

6.0.1 Only re-render changed files

You can add the following to your _quarto.yml file to only re-render changed files:

execute: 
  freeze: auto

When freeze: auto is enabled, Quarto checks for modifications in the source files of your computational documents. If no changes are detected, Quarto will utilize the cached results from previous computations, skipping the re-execution of code chunks.

This significantly speeds up rendering times, especially for large projects with many computational documents. ✅

There are drawbacks: some files may not be updated in time.

  • Use freeze: false to force re-rendering of all files when you are able to submit your changes.
  • Use freeze: auto when you are editing actively and want to see your changes in time.

Strengths of Quarto:

  • hoverable citations and cross-references, easy to read
  • easy subplots

Weaknesses of Quarto:

  • slow compared to Bookdown

    Workaround:

    • Use quarto preview in terminal to enable live preview
    • Set freeze: auto in _quarto.yml to only re-render changed files.

  • Issues when you want to compile one single page within a package. Changes are not reflected in time unless you render the whole website.

    Workaround: Need to exclude from project index, and need file header yaml to import mathjax settings and themes.

    Bookdown is reliable. Don’t need yaml in single Rmd, website theme will apply automatically.

  • Not support rstudioapi functions. E.g., the following is often used to set working directory to the folder where the current script is located.

    But it does NOT work in Quarto.

    # set working dir, return error in Quarto
dir_folder <- dirname(rstudioapi::getSourceEditorContext()$path)
setwd(dir_folder)