Chapter 6 Quarto

Useful resources:

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

Projects

If you have multiple .qmd files in one directory, it’s a good practice to create a project for them.

Benefits of creating a project: ↩︎

Share YAML configuration across multiple .qmd files.

Sometimes yaml gets very long. Put shared YAML options in _quarto.yml file and it will apply to all .qmd files in the same directory. This makes your .qmd files more clean.
Redirect output to a specific folder.
Freeze rendered output, so that only changed files will be re-rendered

Types of projects:

default: default type; plain project, no linking between files.

This is useful if you just want to render multiple .qmd files in the same directory.

If the file _quarto.yml is empty, or if type is unspecified, the type is assumed to be default.
book: enforce chapters, build everything together
website: create navigation, expect index.qmd as the homepage.
blog
manuscript and confluence

6.0.0.1 Create a project

In terminal, run quarto create project and follow the prompts to create a new project.

You can also define the type and name as arguments in the command, e.g., quarto create project <type> <name>.

quarto create project default project-name project-title

Quarto will then create the folder, e.g. project-name and populate it with _quarto.yml and a Quarto document with the same name as the project title, project-title.qmd:

temp-dirs/project-name
├── _quarto.yml
└── project-title.qmd

The file _quarto.yml is also populated with the project title:

project:
  title: "project-title"

You can manually create a project by creating a _quarto.yml file in the directory. The presence of _quarto.yml, even if empty, signals to Quarto this is a project, and allows you to render without specifying a file.

When you run quarto render, Quarto will render all Quarto documents in the project.

Put project metadata in _quarto.yml file. Any document rendered within the project directory will automatically inherit the metadata defined at the project level. Here is an example of what the _quarto.yml file might look like

project:
  type: default

from: markdown+tex_math_single_backslash+markdown_in_html_blocks
bibliography: bibli.bib

format:
  html:
    theme:
      light: [flatly, themes/light.scss]
      dark: [darkly, themes/dark.scss]
    respect-user-color-scheme: true
    toc: true
    css: 
      - ~/Library/CloudStorage/OneDrive-Norduniversitet/_shared-resources/custom-style.css
    self-contained: true
    html-math-method: mathjax
    include-in-header: 
      - ~/Library/CloudStorage/OneDrive-Norduniversitet/_shared-resources/mathjax.html
    fontsize: 14pt
    grid:
      body-width: 1000px

Some YAML options accepts multiple values, you can specify using the block style with dashes - or the inline style with square brackets [].

For example, the include-in-header option accepts multiple values. You can specify it in block style as follows:

include-in-header:
  - mathjax.html
  - custom-style.css

Or you can specify it in inline style as follows:

include-in-header: [mathjax.html, custom-style.css]

include-in-header: Include contents of file, verbatim, at the end of the header. This can be used, for example, to include special CSS or JavaScript in HTML documents or to inject commands into the LaTeX preamble.

css official option can also be used to include CSS files in HTML documents.

Markdown Extensions can be enabled using from option in YAML. For example, from: markdown+tex_math_single_backslash+markdown_in_html_blocks enables the following extensions:

tex_math_single_backslash allows you to use $ and $ to delimit inline math, and \[ and \] to delimit display math.
markdown_in_html_blocks allows you to use markdown syntax within HTML tags.

markdown_in_html_blocks (markdown inside html) seems to be enabled by default in Rmd, but NOT in Quarto or Jekyll websites.

A workaround if you don’t want to enable this extension is to use html innner and markdown outer, e.g.,
```
**<span class="env-green">text</span>**
```
This way, both the html class and markdown bold syntax will apply.

For more on available markdown extensions see the Pandoc Markdown specification.

Note that Rmd enables Markdown extensions differently than Quarto.

Rmd uses the md_extensions option.
Quarto uses the from option.

Both options can be specified under specific output formats, e.g., html or pdf, or as top-level options that apply to all output formats.

Under specific output formats:

---
title: "Habits"
output:
  html_document:
    md_extensions: -autolink_bare_uris+hard_line_breaks
---

Top-level options:

title: "Habits"
md_extensions: -autolink_bare_uris+hard_line_breaks

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.

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)
```