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!