yaml.qmd

# Setting options with YAML {#sec-yaml}

## Overview 

There's a lot going on when you set a Quarto option.
You need to:

-   know the name of the option and the values it can take,
-   figure out where to set the option, and
-   get the YAML syntax right for setting the option to its value.

In this chapter, you'll learn more about setting options in Quarto so you can nail each of those steps.

You'll start by learning more about YAML syntax.
Then, you'll see some ways things can go wrong.
Finally, you'll learn more about how to find out what options are available, and where to put them.

## General YAML syntax

In this section you'll learn the necessary YAML fundamentals to avoid syntax errors when setting options.
Although the syntax applies generally to any YAML, all the examples you'll see are valid Quarto options and values.

### YAML Mappings

A YAML mapping is the specification of a key-value pair using the syntax `key: value`.
Values can be simple, like a string, boolean, or number:

``` {.yaml filename="document.qmd"}
---
title: My Document  #<1>
toc: true           #<2> 
toc-depth: 2        #<3>
---
```
1. A string
2. A boolean, `true`/`false`
3. A number

Or, values can be more complicated like another mapping.
When the value of a key is another mapping, indentation is used to keep track of scope.
For example, here the value of the `author` key is another mapping, setting `name` to the value `Soraya Drake`:

``` {.yaml filename="document.qmd"}
---
title: My document
author:
  name: Soraya Drake
---
```

It doesn't matter how many spaces you indent as long as you use spaces (as opposed to tabs), and use the same number consistently.
A common style convention, and the one we follow in this book and in Quarto documentation, is to use two spaces for each level of indentation.
For example, the `name` key nested under `author` is indented two spaces, whereas the `name` key nested under `affiliation`, which itself is nested under `author`, is indented four spaces:

``` {.yaml filename="document.qmd"}
---
title: My document
author:
  name: Soraya Drake
  affiliation: 
    name: Everpine University    
    url: http://everpine.edu
---
```

The names you can use in Quarto, along with the types of values they take, are not specified by the YAML language, but by Quarto's own schema.

### YAML Sequences

A YAML sequence is a way to provide a key a set of ordered values.
There are two syntaxes to specify a YAML sequence.
When the values in the sequence are simple, separate them with commas inside square brackets:

``` {.yaml filename="document.qmd"}
---
theme: [cosmo, styles.scss]
---
```

The alternate syntax puts each value on its own line, and adds a dash prefix followed by a space:

``` {.yaml filename="document.qmd"}
---
theme: 
  - cosmo
  - styles.scss
---
```

This alternate syntax can also handle situations where the values are further mappings.
For example, here the value of `author` is a sequence of length two, where each element is a mapping of `name` and `affiliation`:

``` {.yaml filename="document.qmd"}
---
title: My document
author:
  - name: Soraya Drake
    affiliation: Everpine University    
  - name: Zahir Kamarov
    affiliation: Peregrine Heights Institute
---
```

### YAML Scalars

YAML uses the term *scalar* to talk about the simplest types of value: strings, numbers, and booleans.
You saw an example of each earlier:

``` {.yaml filename="document.qmd"}
---
title: My Document  # A string
toc: true           # A boolean, `true`/`false`
toc-depth: 2        # A number
---
```

The only values recognized as boolean are `true` and `false`; numbers can be single integers (`2`), decimals (`2.1`), or scientific (`2.1e+2`), and anything else is treated as a string.

::: callout-tip
## YAML comments

The hash symbol (`#`) indicates the start of a comment, which is ended by the end of the line.
:::

### Quotes

Strings don't require quotes, but you may need them if your string contains characters that have special meaning in YAML (e.g. `#`, `:`, etc.), or is something that would otherwise be interpreted as a number or boolean:

``` {.yaml filename="document.qmd"}
---
title: "Quotes: and things that need them"  
author: "#quarto"
subtitle: "100"
---
```

In YAML, double-quoted strings (`"`) allow escape characters in them, whereas single-quoted strings (`'`) are interpreted literally:

``` {.yaml filename="document.qmd"}
---
title: "Quotes: \U0001F4E8"
subtitle: 'Quotes: \U0001F4E8'
---
```

Q: where does the `\U` go in `subtitle` go?
YAML might be interpreting literally but Quarto/Pandoc might escape somewhere?

### Long strings

For strings that are longer than you'd comfortably put on a single line, or need explicit line breaks, you can use what YAML calls **block scalars** \index{block scalar}.

There are two styles: literal and folded.

Literal block scalars are indicated by a pipe (`|`), and line breaks are considered significant, whereas folded block scalars are indicated by a greater than symbol (`>`), and line breaks are collapsed to spaces.

In both cases, start your string on a new line indented under the key:

::: {layout-ncol="2"}
``` {.yaml filename="literal.qmd"}
---
title: |
  A title

  spanning two lines
---
```

``` {.yaml filename="folded.qmd"}
---
title: >
  A title

  collapsed into one line
---
```
:::

::: {#fig-block-strings layout-ncol="2"}
![Rendered title using literal (`|`) block scalar](images/yaml-block-literal.png){#fig-block-strings-literal .border fig-alt="A screenshot of a title that reads 'A title' then a line break followed by 'spanning two lines'."}

![Rendered title using folded (`>`) block scalar](images/yaml-block-folded.png){#fig-block-strings-folded .border fig-alt="A screenshot of a title that reads 'A title collapsed into one line' all on a single line."}
:::

Depending on where the string value is used, line breaks may or may not mean anything to Quarto.
For instance, when interpreted as markdown, a single line break doesn't result in anything in the output.
However, a double line break will be interpreted as a new paragraph.

### Using `default`

You'll come across examples where the value of a Quarto option is `default`, like when you are specifying multiple formats:

``` {.yaml filename="document.qmd"}
---
format:
  html: default
  pdf: default
---
```

The value `default` doesn't have a special YAML meaning--- it's something Quarto adds for certain options where the value is usually another mapping, but you just want the default values for all properties.

## What happens when you get it wrong?

When you render a project or document, one of the first things that happens is the options are parsed and validated.
When you make a mistake in setting an option there are a few possible outcomes:

1.  You get an error message, and the error message clearly points out your mistake.

2.  You get an error message, but it's not clear from that message what or where your mistake is.

3.  You don't get an error message at all.

It's hard to enumerate all the ways you can make a mistake, but we'll give a couple of examples for each of these outcomes in the hope it helps you track down yours.

Some examples in this chapter will result in an error from `quarto render`---we've highlighted these examples with a red border (TODO: add an icon for PDF version), like this:

``` {.yaml .error filename="render_error.qmd"}
---
title: Bad YAML : (
---
```

::: callout-note 

The error messages shown in the text are current as of Quarto 1.6.

:::

We've split the examples by the kind of mistake you make:

-   Using the wrong YAML syntax
-   Using the wrong name for an option
-   Using the wrong type of value for an option

### Using the wrong YAML syntax

When your YAML can't be parsed by Quarto you'll get a `YAMLException` error.
These are actually surprisingly rare, not because everyone is great at YAML, but because most YAML syntax mistakes don't result in invalid YAML.
The YAML remains valid, it just won't be interpreted in the way you intended.

For example, if you forget the space after a colon when setting an option like `code-fold`:

``` {.yaml .error filename="document.qmd"}
---
title: "Untitled"
format:
  html:
    code-fold:true
---
```

Then you don't get a `YAMLException` but instead a validation error:

``` default
Validation of YAML front matter failed.
(line 5, columns 5--18) Field "html" has value code-fold:true, which must instead be an object

✖ The value code-fold:true is a string.
ℹ The error happened in location format:html.
ℹ In YAML, key-value pairs in objects must be separated by a space.
ℹ Did you mean code-fold: true instead?
```

The YAML has been parsed, but with the missing space `code-fold:true` was interpreted as a string not a mapping.
Quarto does a good job here suggesting what your mistake might have been and a solution.

Generally, if you get a validation error, first check your syntax carefully.

### Specifying the wrong key

There are some instances where when you use the wrong name for an option you'll get an error.
For example, if you pluralize the `lightbox` option `loop`:

``` {.yaml .error filename="document.qmd"}
title: "Presentation"
format: html
lightbox: 
  loops: true 
```

You'll get a YAML validation error that catches and reports the problem:

``` default
ERROR: Validation of YAML front matter failed.
ERROR: In file long-string.qmd
(line 5, columns 3--8) property name loops is invalid
4: lightbox: 
5:   loops: true 
    ~~~~~~
ℹ The error happened in location lightbox:loops.
ℹ Did you mean loop?
```

Options where Quarto only allows a certain set of property names are known as **closed schemas**, e.g., the `lightbox` option has a closed schema.
However, not all Quarto options have closed schemas.

When the schema is *open*, Quarto simply accepts an unknown option name and you get no error.
For example, you might use an underscore instead of a hyphen in `code-fold`:

``` {.yaml filename="document.qmd"}
---
title: My document
format: 
  html:
    code_fold: true
---
```

Even though `code_fold` isn't a recognized option for `html`, you'll get no error.
But, you also won't get any code folding.
Why does Quarto have open schemas?
There are lots of places it makes sense to let users define their own keys, for example, when you want to use the `meta` shortcode and define some custom keys in your metadata.

A similar problem occurs when you nest options incorrectly.
For example, you might get `code-fold` right, but forget to nest `html` under `format`:

``` {.yaml filename="document.qmd"}
---
title: My document
html:
  code-fold: true
---
```

As a top-level option `html` isn't something Quarto knows about, but it passes validation.
The result is no error, and no folded code.

[Code completion](#yaml-completion) can be a useful indicator for these problems.
If you aren't getting the completion you expect, perhaps you've got the wrong name, or you've nested it under the wrong option.

### Specifying the wrong type of value

Checking the type of value you've passed is something Quarto is good at, assuming your syntax is correct and you've got the right option name.

For example, consider trying to add a table of contents like this:

``` {.yaml .error filename="document.qmd"}
---
title: My document
toc: yes
---
```

Upon render, Quarto returns the error:

``` default
ERROR: Validation of YAML front matter failed.
ERROR: (line 3, columns 6--8) Field "toc" has value yes, which must instead be `true` or `false`

✖ The value yes is a string.
ℹ The error happened in location toc.
ℹ Quarto uses YAML 1.2, which interprets booleans strictly.
ℹ Try using true instead.

ERROR: Render failed due to invalid YAML
```

This is a really useful message---it tells you the YAML front matter validation failed; it tells you where the problem is, `(line 3, columns 6--8) Field "toc"`; and it tells you what the problem was, Quarto expected a boolean, but got a string.
It even suggests a solution `try using true instead`.

Not all validation error messages are as illuminating.
For example, consider trying to add an "Other Link" like this:

``` {.yaml .error filename="document.qmd"}
---
title: "Untitled"
format:
  html:
    other-links: http://quarto.org
---
```

The validation error returned is:

``` default
ERROR: Validation of YAML front matter failed.
ERROR: In file type-errors.qmd
(line 5, columns 18--34) Field "other-links" has value http://quarto.org, which must instead be 'false'
4:   html:
5:     other-links: http://quarto.org
                   ~~~~~~~~~~~~~~~~~
6: ---
```

It's clear where the error is (`(line 5, columns 18--34) Field "other-links"`), and that the wrong type of value has been encountered.
But it's unclear what Quarto actually wants.
It says it was expecting `false`, but that doesn't help us figure out how to actually specify a link.

::: callout-tip
## Obtuse messages

Quarto tries not to overwhelm you with output in an error message, but sometimes the process of shortening an error message leads to a message that isn't very helpful.

This particular form of message that ends with `which must instead be x`, is a common culprit of being too brief to be helpful.
Quarto will often report one value, `x`, often the first alphabetically, but in reality there are many values that the option could take.
:::

For validation errors like this you should look for an example in the Guide section of Quarto.
In the section ["Code and Other Links"](https://quarto.org/docs/output-formats/html-basics.html#code-links-and-other-links) you can see an example showing Quarto was expecting an array of objects:

``` {.yaml filename="document.qmd"}
---
title: "Untitled"
format:
  html:
    other-links: 
      - text: Quarto
        href: http://quarto.org
---
```

### Ways Quarto tries to help

Quarto ships with YAML intelligence which encompasses two tools you can use to help you get your YAML right: YAML completion and YAML validation.

These tools are available in RStudio, and the Quarto extension for VS Code and Positron.
The code to implement them comes with the Quarto CLI, which means they'll always represent your current version of Quarto.

#### YAML completion {#yaml-completion}

YAML completion suggests code completions when you are editing YAML in your Quarto documents and projects.
You can hit a shortcut to see suggested completions of option names, and values.

Use completion:

-   At the top-level without typing anything to remind yourself of available options.
-   When you have started typing an option name to avoid mis-spelling it. If the option doesn't appear as a completion, check you have it nested correctly.
-   After completing the option name to get suggested values. This is particularly useful for options that take one of a few special strings.

#### YAML validation

YAML validation performs the same validation that occurs when you render, but provides feedback and help where and when you are editing.
It is activated when you save your file.

It will warn you when:

-   a value has the incorrect type
-   a value isn't one of the enumerated allowable values
-   the name of an option isn't valid (but only in situations where free-form options aren't allowed)
-   indention is inconsistent

## What are the possible options?

The best place to find out what options are available is the [Reference section of the Quarto documentation](http://quarto.org/docs/reference).
These pages are automatically generated from the YAML schema defined in the source code of the Quarto CLI.

The options available depend on where the option will be applied.
From smallest to largest scope these are: to a code cell, to a document format, or to a project.

Those scopes also map to where you put the option: inside the code cell, in the document header, or in `_quarto.yml`.
However, you can generally apply options to a larger scope, by placing them in the corresponding location.
For example, `echo` is a code cell option, but you can use it in the document header to apply to formats, or you can use it in `_quarto.yml` to apply to all documents in a project.

@tbl-options matches the sections of the Reference Guide, 
to the other names for the same options, and where the options might be found.
In the following sections, you'll work through these scopes from largest to smallest and learn some general principles to help you put your options in the right place.

+-------------------------+-------------------+-----------------------------+
| Reference Guide Section | Other names       | Where they might occur      |
+:========================+:==================+:============================+
| Projects                | Project options   | `_quarto.yml`               |
|                         |                   |                             |
|                         | Project metadata  |                             |
+-------------------------+-------------------+-----------------------------+
| Formats                 | Document options  | Document header             |
|                         |                   |                             |
|                         | Document metadata | `_quarto.yml`               |
|                         |                   |                             |
+-------------------------+-------------------+-----------------------------+
| Code Cells              | Execution options | Code cells, i.e. after `#|` |
|                         |                   |                             |
|                         |                   | Document header             |
|                         |                   |                             |
|                         |                   | `_quarto.yml`               |
+-------------------------+-------------------+-----------------------------+

: The three kinds of options you can set in Quarto {#tbl-options}


## Project options

Project options are literally those listed under `project` in `_quarto.yml`, 
or under a project type (e.g., `website`, `book`, or `manuscript`) in `_quarto.yml`.
You cannot modify them on a document or code-cell level, 
nor does it generally make sense to.
For example, options under the `website` key set up global navigation, and
website level metadata.

Project options aren't the only thing you might find in `_quarto.yml`. 
You can also set document options that should apply to all documents in `_quarto.yml`,
you'll learn more about this next.

## Document options

Document options can be tricky because they can appear in lots of different ways.
For example, the `toc` option might appear:

*  at the top-level of a document header:

    ```{.yaml filename="document.qmd"}
    ---
    title: My document
    format: html
    toc: true
    ---
    ```

* nested under a format in the document header:

    ```{.yaml filename="document.qmd"}
    ---
    title: My document
    format: 
      html:
        toc: true
    ---
    ```

* or in `_quarto.yml`:

    ```{.yaml filename="_quarto.yml"}
    toc: true
    ```

To understand what these variations mean, and when to use them, you'll dive into the following principles:

-   Everything is a format option
-   Top-level options are applied to all formats
-   Options in `_quarto.yml` apply to all documents

### Everything is a format option

Consider the following document header:

``` yaml
---
title: My document
toc: true
format: html
---
```

From Quarto's perspective, this is equivalent to the header:

``` yaml
---
format:
  html:
    title: My document
    toc: true
---
```

That is, the options `title` and `toc` are HTML format options.
It's convenient to be able to put things at the top-level, but internally, Quarto will move those options under each format.
This is why Quarto's [reference pages](https://quarto.org/docs/reference/) are laid out by format---options are supported, or not, depending on the output format.

::: callout-note
## OK, not quite everything...

`engine` is an option that isn't applied at a format level---you cannot specify different engines for different formats.
:::

### Top-level options are applied to all formats

Quarto assumes any options you specify at the top-level should be applied to all formats.
For example, if we extend our document header to add the `pdf` format:

``` yaml
---
title: My document
toc: true
format: 
  html: default
  pdf: default
---
```

Quarto interprets this as:

``` yaml
format:
  html:
    title: My document
    toc: true
  pdf: 
    title: My document
    toc: true
```

This is a good example of why this behavior exists---you'll want many options to be the same across formats, and being able to specify them at the top-level saves a lot of typing.

Option values nested under a format will override any specified at the top level.
For example, you might want `toc: true` for most formats, but override it for `revealjs`:

``` yaml
---
title: My document
toc: true
format: 
  html: default
  pdf: default
  revealjs:
    toc: false
---
```

There are a couple of consequences of this behavior to be aware of:

-   Options are silently ignored by formats that don't support them.
    While this is true regardless of where you set the option, it can be harder to remember when you set options at the top-level.
    For example, you can set `cold-fold: true` at the top-level, and it will work great for `format: html`, but it isn't supported by `format: pdf`.

-   YAML completion will suggest options at the top-level that are supported by at least one format, but that might not be the format you targeting.
    For example, the completion `fig-pos` is suggested at the top-level, but it only applies to `format: pdf`.

Both are reminders that understanding whether an option is supported by a format is up to you, and the best way to check is on the Quarto reference pages for the formats you are targeting.

### Options in `_quarto.yml` apply to all documents

You can move any options you've set in the document header to `_quarto.yml` and they'll apply to all documents in your project.

For example, if you want all documents in the project to have a table of contents you could include `toc: true` in your `_quarto.yml` file:

``` {.yaml filename="_quarto.yml"}
toc: true
```

::: callout-note
## `engine` is the exception again

You can't set `engine` at the project level by putting it in `_quarto.yml`.
:::

Options specified in `_quarto.yml` follow the same principles as those in the document header.
By specifying `toc: true` at the top-level it will apply to all formats.
Alternatively, you could specify it for a specific format, e.g. `pdf`, by nesting it under the format:

``` {.yaml filename="_quarto.yml"}
format: 
  pdf:
    toc: true
```

As discussed in @sec-common-metadata you can override any options in `_quarto.yml` at a document-level by setting them in the document header.
However, if you specify any formats via `format` in a document header, only those specified will be rendered, regardless of which formats are specified in `_quarto.yml`.
This gets a little tricky, so let's look at a couple of examples.
Consider @lst-project-opts: a `_quarto.yml` that sets one top-level option, `toc`, for all formats, an `html` option `code-fold`, and specifies default options for the `pdf` format.

::: {#lst-project-opts}
``` {.yaml filename="_quarto.yml"}
toc: true
format: 
  html:
    code-fold: true
  pdf: default
```

An example of project level options
:::

For any document in the project, that would be equivalent to setting the following in the document header:

``` yaml
---
format:
  html:
    toc: true
    code-fold: true
  pdf:
    toc: true
---
```

The result of `quarto render` would be an HTML document (with a table of contents and using code fold), **and** a PDF document (with a table of contents).

When a document sets a format via `format` either with no options (@lst-format-no-opts) or as the result of setting an option nested under the format (@lst-format-opts), only the options for that format are merged from `_quarto.yml` (@lst-format-result-no-opts and @lst-format-result-opts respectively).
The result of `quarto render` on @lst-format-no-opts and @lst-format-opts is only an HTML document.

::::: {#lst-format}
::: {#lst-format-no-opts}
``` yaml
---
format: html
---
```

`format: html` set with no other options.
:::

::: {#lst-format-opts}
``` yaml
---
format: 
  html:
    toc: false
---
```

`format: html` set with additional options.
:::

A document that sets a format in the document header
:::::

::::: {#lst-format-result}
::: {#lst-format-result-no-opts}
``` yaml
---
format: 
  html:
    toc: true
    code-fold: true
---
```
:::

::: {#lst-format-result-opts}
``` yaml
---
format: 
  html:
    toc: false
    code-fold: true
---
```
:::

The equivalent header for the files in @lst-format when merged with the settings in `_quarto.yml`.
:::::

If you want to specify some format specific options in a document, but maintain the full list of target formats from `_quarto.yml`, specify all formats in the document header.
For example, to override some HTML options, but use the PDF options from `_quarto.yml`, add `pdf: default` to the list of formats:

``` yaml
---
format: 
  html:
    toc: false
  pdf: default
---
```

### `_metadata.yml`

There is one additional place you can put document options: in a `_metadata.yml` file.
Options placed in `_metadata.yml` will apply to all documents in the same directory as the `_metadata.yml`.

Only for document options (and execution options if they have a document equivalent), not project options.

### Command line metadata

Command line metadata overrides metadata set in files:

``` {.bash filename="Terminal"}
quarto render document.qmd -M toc:false
```

## Execution options

We use the term **execution options** to describe options you can set in code cells. 
The set of options available depends on your execution engine:
[`knitr`](https://quarto.org/docs/reference/cells/cells-knitr.html), [`jupyter`](https://quarto.org/docs/reference/cells/cells-jupyter.html) or [`ojs`](https://quarto.org/docs/reference/cells/cells-ojs.html).

You can generally split execution options into two types:

-  information that is unique to a code cell like identifiers (`label`, `lst-label`), captions (`fig-cap`, `tbl-cap`, `lst-cap`, `fig-subcap`, `tbl-subcap`, `fig-scap`) or other annotation (`fig-alt`, `fig-link`).

-  settings that could conceivably apply to many code cells that control things like: if the code is executed (`eval`), or how code and results appear in the output(`echo`, `output`, `warning`, `error`), where output appears (`column`, `panel`, `output-location`), or how code is presented (`code-fold`, `code-overflow`, `code-line-numbers`).

For options in the later category, just like document options, you can increase their scope by moving them: to the document header to apply to all code cells in the document; or to `_quarto.yml` to apply to all code cells in the project.

### Execution options set in code cells

Execution options are set in code cells using YAML syntax after a special comment:

````
```{{r}}
#| echo: false

```
````

Execution options need to be specified before any code, 
and are prefaced by the native comment character for the 
code cell language (`#` for `r`, `python` and `julia`),
followed by a pipe (`|`), and a space.

You can use the same YAML syntax as in the document header, 
but for multiline statements, remember to preface each line with the cell option comment.
For example, to use a literal block string:

````
```{{r}}
#| fig-cap: |
#|   Here's a long caption
#|   spread over two lines

plot(1:10)
```
````

### Execution options set in the document header

As reasonable working model, assume you can move an execution option from a code cell to the document header and it will apply to all code cells in the document.
For example, you could move `echo: false` out of a code cell and into the document header:
```{.yaml filename="document.qmd"}
---
title: My document
echo: false
---
```

You can override the document level setting by setting the option in a code cell:

````
```{{r}}
#| echo: true

```
````

When you move an option in this way it behaves just like a document option:

1. To figure out if an option is supported at the document level look in the reference guide for your target formats.

2. If you nest an execution option under a format, it will only apply to that format.

So, while assuming you can move an execution option to the document header is a good working model, the definitive way to check is to see if it is a document option for your target formats.

There are a couple of special cases it is worth pointing out.

### `fig-width` and `fig-height`

For the `jupyter` engine, `fig-width` and `fig-height` are document options only---you cannot set them at the cell level. 
If you need cell level control of the size of a figure, you'll need to set it in the code that creates the figure.

### Knitr specific options 

There are a number of execution options that are specific to the `knitr` engine, that don't have document option equivalents.
Some common ones include `message`, `collapse` and `prompt`.

You can set these for all code cells using the `knitr: chunk_opts` option.
For example, to suppress all messages:

```{.yaml}
---
title: "Untitled"
format: html
knitr:
  opts_chunk:
    message: false
---
```

### Execution options set in `_quarto.yml`

When an execution option is also a document option, 
you can move it to `_quarto.yml` to apply to all code cells in a project.

For example, to omit the code "echo" all code cells, and all formats, in a project you could set `echo` at the top-level of `_quarto.yml`:

```{.yaml filename="_quarto.yml"}
echo: false
```

You can then override this at the document or cell level as usual.