Documentation for all YAML options

[liquidcarbon]

Description

Hi there,
I'm often finding myself bouncing around Quarto documentation, looking for a specific tweak that could be enabled through a YAML setting. It would be nice if there was a page documenting ALL the options. Does this exist?

With my friend Chat G., I wrote a quick and dirty scraper for all .qmd files in the quarto-web repo and came up with the following list of YAML keys (indentation preserved). Could this be a starting point?

  zotero
  website
  version
  tool
  toc
  title
  subtitle
  spec
  server
  search
  resources
  provider
  project
  params
  pagetitle
  mainfont
  listing
  license
  language
  lang
  keywords
  jupyter
  image
  github
  geometry
  funding
  from
  format
  fontsize
  filters
  execute
  engine
  editor_options
  editor
  draft
  description
  date
  css
  csl
  crossref
  copyright
  contributes
  comments
  citeproc
  citation
  categories
  bibliographystyle
  bibliography
  author
  aliases
  affiliation
  abstract
  about
    year
    warning
    volume
    url
    typst
    type
    text
    template
    statement
    sort
    revealjs
    repo
    ratio
    preview
    pptx
    pdf
    owner
    orcid
    name
    markdown
    links
    light
    labels
    kernelspec
    is_vscode
    is_rstudio
    is_jupyterlab
    issued
    issue
    issn
    ipynb
    include
    image
    id
    hypothesis
    html
    holder
    gfm
    fr
    formats
    fields
    feed
    exclude
    enabled
    en
    email
    echo
    doi
    docx
    dark
    corresponding
    contents
    chapters
    categories
    cache
    beamer
    alpha
    affiliation
      wrap
      width
      url
      typst
      transition
      touch
      toc
      title
      theme
      template
      smaller
      scrollable
      references
      progress
      port
      pointer
      path
      orcid
      navigation
      name
      multiplex
      minimal
      mermaid
      lot
      loop
      logo
      lof
      language
      investigator
      incremental
      id
      history
      height
      geometry
      footer
      fontfamily
      email
      echo
      documentclass
      display_name
      css
      corresponding
      controls
      contents
      columns
      colortheme
      colorlinks
      classoption
      chalkboard
      categories
      canonical
      browser
      author
      aspectratio
      affiliations
      affiliation
       toc
        url
        title
        theme
        text
        template
        state
        src
        source
        secret
        ringgold
        prefix
        pointerSize
        path
        location
        links
        isni
        id
        href
        given
        family
        department
        date
        country
        color
        city
        buttons
          url
          state
          name
          department
          country
          city
          address

This isn't a full list - the script is only looking at the frontmatter (stuff between triple dashes).

To reproduce:

git clone https://github.com/quarto-dev/quarto-web.git
./find_yaml.sh quarto-web | egrep "^\s+\w+:" | cut -d: -f1 | sort -rfu

where find_yaml.sh is:

#!/bin/bash

search_directory="$1"
file_extension=".qmd"  # Change the file extension if needed

# Function to extract and process YAML blocks
extract_yaml_blocks() {
    local content="$1"
    yaml_blocks=()
    in_yaml_block=false
    current_yaml=""

    while IFS= read -r line; do
        if [[ $line == "---" ]]; then
            if $in_yaml_block; then
                in_yaml_block=false
                yaml_blocks+=("$current_yaml")
                current_yaml=""
            else
                in_yaml_block=true
            fi
        fi

        if $in_yaml_block; then
            current_yaml+="$line"$'\n'
        fi
    done <<< "$content"

    echo "${yaml_blocks[@]}"
}

# Main loop to process files
find "$search_directory" -type f -name "*$file_extension" | while IFS= read -r file_path; do
    echo "Processing $file_path ..."
    file_content=$(cat "$file_path")
    yaml_blocks=$(extract_yaml_blocks "$file_content")

    for yaml_block in "${yaml_blocks[@]}"; do
        echo "$yaml_block" | sed -e 's/^/  /'
    done

[cscheid]

Do you mean a single page? There are about 1000 different YAML options, we don't think a single page like that would be helpful. With that said, we do have an entry point for YAML options here, and it should be searchable as well: https://quarto.org/docs/reference/

[liquidcarbon]

I was thinking of a single page, yes, with enumeration of the options if possible. I agree that's not easy to make it effective and even to put it together in the first place.

The reference pages are great. But it can be a little hard to find a specific option, and how to use it. For example, the entry for grid in https://quarto.org/docs/reference/formats/html.html#layout only says "Properties of the grid system used to layout Quarto HTML pages" and the actual usage is documented in https://quarto.org/docs/output-formats/page-layout.html#grid-customization

Searching for "grid" (or anything else that's fairly common) gives you many options and it's not clear right away where to go. Maybe an option to only search for YAML keys could be helpful?

[2handluke]

It would absolutely be helpful for me. As someone who wants to use R and quarto, this feels like a real barrier for learning. I think this should be in the guide section (not in references, or with a VERY clear way to find it from the guide) for each output type: https://quarto.org/docs/reference/formats/presentations/revealjs.html

Also as someone who isn't too experienced with this, how am I supposed to know which options belong where in the YAML in that documentation? Not all of those revealjs option work wherever you put them, some have to be indented below revealjs some you don't!

[LJFRIESE]

+1 for finding the learning curve steep (surmountable, but steep) for working out where in the guides/reference one needs to look to find different types of information. I still do a lot of blind testing of different options/formats for YAML because it's not always clear. Currently working through this in mermaidjs for Quarto...

[spider-z3r0]

This would be a brilliant thing, like a searchable dictionary of yaml options. I'd be happy to write one, but I can't find a reference to get me started.

[2handluke]

This should not be in references, this took me absolutely forever to find. I think it should be in reveal js overview slides, where in any of those slides was i supposed to find this: https://quarto.org/docs/reference/

[anacolla2]

Thank you! A single overview/scope list of YAML options is perfect. I'm shocked it wasn't already available!

[jemus42]

Just to provide a motivating example for an index-like full reference:

I came here because I have habitually used the following on both RStudio + RMarkdown and Quarto + Positron

editor_options:
  chunk_output_type: console

And I was trying to find out

a) if I can specify this option in a _quarto.yaml
b) If there are other editor_options I might want to know about
c) What even is this option (it's unique to RStudio or Positron and apparently also not unique to RMarkdown or Quarto, so is it technically an execution option relevant for.. knitr?

And after some googling around and not directly useful information on the quarto website I ended up here, and still have no idea which other editor_options are actually available, or if I should use editor: instead :)

As much as I appreciate everything quarto can do, I regularly get confused with YAML options and at which point exactly I can or can not use which options, particularly with the layers of Quarto project level / quarto format level / pandoc / execution level (knitr in my case), and often the website has me running around in circles 😅

[mcanouil]

editor_options is more of an IDE setting than a Quarto or RMarkdown setting.
For instance, the VSCode-R extension for VSCode or VSCode itself does not know at all what this is, regardless of your document being a Quarto or RMarkdown document.

Note that Quarto CLI uses dash as word delimiters in options.

editor is in some aspects also an IDE option but targeted for Quarto where the two only values are: source or visual (Visual Editor). This option is actually not used by Quarto CLI. It's used by the extension for VSCode/Positron.

So the real question is: where do Positron and RStudio are looking for "editor_options"? Rather than is t a Quarto CLI options.

Regarding the list all YAML options, if you want to include, everything from IDE, to third parties, you will likely end up with several thousands options.
For now, you still have a quite long list of options referenced in the "references" pages (they don't include all Pandoc's options, for that you mostly have to look in Pandoc's documentation).

• https://quarto.org/docs/reference/

[mcanouil]

FWIW, I never seen editor_options being documented in RStudio documentation.
The only place that I ever found out about this (outside of user reports) is the R Markdown Cookbook

RStudio code showing support of the option:

• https://github.com/rstudio/rstudio/blob/76afe55c5e0a1922e16c5e9a9516fcec33522634/src/gwt/src/org/rstudio/studio/client/rmarkdown/model/RmdEditorOptions.java#L103-L112

Positron support (via the quarto extension):

• https://github.com/quarto-dev/quarto/blob/8f99af79d465361c1503dce40a85ba10fe8bd48d/packages/editor/src/api/pandoc_format.ts#L76

[jemus42]

Thanks! Yeah, that checks out, I assume I got editor_options form the Cookbook as well.

And well, I only ended up in this thread because of an exact text match for editor_options from OP's post enumerating all the YAML options, so I assumed maybe quarto at least knew about this, but it makes sense for this to be IDE specific.