Chapter 6 Quarto

Install: https://quarto.org/docs/get-started/

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 and cluttered. To makes your .qmd files cleaner and neater, put shared YAML options in _quarto.yml file and it will apply to all .qmd files in the same (sub-)directory.

In each .qmd file, you provide file-specific YAML options, e.g, title, author, date, etc.

Always create a _quarto.yml file in the root of your project directory and put your shared YAML options there.
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.

book type supports multiple output formats, e.g., PDF, HTML, EPUB, DOCX, etc. HTML books are a special type of Quarto Website. So they support all Quarto Website features.

One distinction between book and website is that when you have pdf output, book will compile all chapters into a single pdf file, while website will compile each chapter into a separate pdf file.

Use book type for course materials so that you have a single pdf file for the whole course.
website: create navigation bar, 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.

YAML Metadata

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

Use format to specify output formats. This is different from Rmd, which uses output to specify output formats. See HERE for Quarto equivalents of document formats in Rmd.

Multiple output formats can be specified in the format section. For example, you can specify both html and pdf outputs as follows:

---
title: "My Document"
format:
  html: default
  pdf: default
---

Then when you run quarto render my-document.qmd, Quarto will render both HTML and PDF outputs.

If you want to render only one format, you can specify the format in the command line, e.g.,

# Render only HTML output
quarto render my-document.qmd --to html

# Render only PDF output
quarto render my-document.qmd --to pdf

If you want to specify options for each format:

---
title: "My Document"
format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
---

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

You can specify it in block style as follows:
```
include-in-header:
  - mathjax.html
  - custom-style.css
```
css official option can also be used to include CSS files in HTML documents.

Or you can specify it in inline style as follows:

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

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

Quotes in the title allow escape characters, e.g., # and : have special meaning in YAML, so you need to use quotes to escape them. Quotes are NOT required if the title does not contain special characters.

Use title: | to allow line breaks in the title. | (pipe symbol) is called the literal block scalar. The pipe indicates that (except for the indentation) the scalar value should be interpreted literally in such a way that preserves newlines. See the YAML spec.

It will escape special characters, so you can use \ to insert line breaks in the title.

title: |
  Quarto: \
  A Practical Guide

Alternatively, you can use

title: |
  Quarto:

  A Practical Guide

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.

A folder named _freeze will be created in the project directory to store the cached results. It lets Quarto render without re-executing every code chunk.

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.

.quarto/ is a build directory that contains the intermediate files generated during the rendering process. It stores things related to the project’s internal processing, generated state. Each render will create a large number of changes in .quarto/ folder. It is safe to delete it, as Quarto will regenerate it during the next render.

Given the large number of changes in .quarto/ folder, never sync it. For git, add .quarto/ to your .gitignore file. For OneDrive,

Create a new ~/.quarto-cache/ directory on local disk,
Create a symbolic link .quarto in your project directory to point to the new cache directory.

This way, when you render the project, the intermediate files will be stored in the new cache directory, and not synced to OneDrive. See HERE for more details.

Strengths of Quarto:

Live preview.

This is NOT supported in Rmd.
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.
Quarto’s way of cross references equations is NOT compatible with latex labels. Quarto’s way does not handle multilined equations labeling well. See HERE for details.
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)
```