Customize with YAML

1 Introduction to YAML

YAML (YAML Ain’t Markup Language) is a human-readable data serialization format that Quarto uses to configure documents and control their behavior. Think of YAML as a set of instructions that tell Quarto how to process and present your document.

Key benefits of YAML: - Simple, readable syntax - Flexible configuration options - Separates content from formatting - Allows consistent styling across documents

2 Basic YAML Syntax Rules

YAML follows some simple but important rules: - Uses key-value pairs (e.g., title: "My Document") - Is indent-sensitive (typically 2 spaces) - Values can be strings, numbers, booleans, lists, or nested structures - Strings don’t usually need quotes unless they contain special characters

Example of different YAML syntax elements:

# Simple key-value
title: "My First Quarto Document"

# List items (using hyphens)
author:
  - "Jane Smith"
  - "John Doe"

# Nested structures
format:
  html:
    toc: true
    number-sections: true

3 YAML Headers

HTML Output Example

format:
  html:
    theme: cosmo
    css: custom.css
    toc: true
    toc-depth: 3
    toc-location: left
    toc-title: "Contents"
    code-fold: true
    code-tools: true
    code-copy: true
    code-line-numbers: true
    number-sections: true
    number-depth: 3
    fig-width: 8
    fig-height: 6
    fig-format: svg
    fig-dpi: 300
    embed-resources: true
    page-layout: article
    fontsize: 1.1em
    linestretch: 1.5
    title-block-banner: true
    smooth-scroll: true
    anchor-sections: true
    search: true

Let’s break down these options:

Theme Options Available themes in Quarto:

Default themes:

default: Clean, minimal styling
cosmo: Modern and sleek
flatly: Flat design with bold colors
journal: Traditional academic style
lumen: Light and airy design
sandstone: Friendly and accessible
simplex: Minimalist but refined
spacelab: Industrial and practical
yeti: Modern and versatile

Bootswatch themes:
cerulean: Blue and light blue
litera: Literary, serif-focused design
darkly: Dark background theme
cyborg: High contrast, dark theme
minty: Fresh, light theme
pulse: Vibrant and bold
sketchy: Hand-drawn style
slate: Shades of grey
solar: Dark with green accents
united: Ubuntu-style theme
vapor: Retro cyberpunk style
zephyr: Red and blue accents

Page Layout Options

article: Fixed-width, centered layout (default) - Best for reading-focused content - Maximum width of about 900px
full: Full browser width - Useful for dashboards - Content uses all available space
custom: Define your own width - Requires additional CSS specifications - Allows for precise control of layout

Code Appearance Options

format:
  html:
    code-fold: true        # Adds a code fold button
    code-tools: true       # Adds a toolbar above code blocks
    code-copy: true        # Adds copy button to code blocks
    code-line-numbers: true # Adds line numbers
    code-block-bg: true    # Adds background color to code blocks
    code-block-border-left: "#31BAE9" # Adds left border to code blocks
    code-overflow: wrap    # Controls how code handles overflow
    code-link: true       # Makes code chunks linkable

PDF Output Example

format:
  pdf:
    documentclass: article
    classoption: 
      - twocolumn
      - landscape
    papersize: letter
    geometry:
      - top=1in
      - left=1in
      - right=1in
      - bottom=1in
    fontsize: 11pt
    linestretch: 1.5
    colorlinks: true
    lot: true        # List of tables
    lof: true        # List of figures
    highlight-style: github
    include-in-header: header.tex
    keep-tex: true

Document Class Options Available document classes:

- article: Standard academic articles

- Options: - twocolumn: Two-column layout

- onecolumn: Single-column layout

- titlepage: Separate title page

- notitlepage: Title on first page

- landscape: Landscape orientation

- draft: Draft mode with visible overfull boxes

- final: Final document mode

- leqno: Left equation numbers

- fleqn: Left-aligned equations

- openbib: Open bibliography style

report: Longer documents with chapters
- Additional options:
  - openright: Chapters start on right pages
  - openany: Chapters start on any page
book: Full book formatting
- Additional options:
  - openright: Chapters start on right pages
  - openany: Chapters start on any page
  - oneside: Single-sided printing
  - twoside: Double-sided printing
beamer: Presentation slides
- Options:
  - aspectratio=169: Widescreen format
  - handout: Removes animations
  - notes: Includes speaker notes

4 Language and Bibliography

lang: en-US
bibliography: references.bib
csl: apa.csl
cite-method: citeproc
link-citations: true
link-bibliography: true
reference-location: margin
citation-location: margin

5 Execute Options

execute:
  echo: true        # Show code chunks
  eval: true        # Evaluate code chunks
  warning: false    # Hide warnings
  message: false    # Hide messages
  error: false      # Hide error messages
  include: true     # Include chunk output
  cache: true       # Cache results
  freeze: auto      # Auto-freeze computational output
  fig-path: "figures/"  # Path for generated figures
  fig-format: "png"    # Default figure format

6 YAML Locations

There are three main locations where YAML configurations can be specified in Quarto:

1. Document headers

2. Code chunks

3. Project-level _quarto.yml files

Understanding when to use each location helps create more maintainable and efficient documents.

6.1 Understanding the Hierarchy

YAML settings follow a precedence order: 1. Code chunk options (highest priority) 2. Document YAML header 3. Project YAML file (lowest priority)

This means that more specific settings override more general ones. For example, a code chunk setting will override the same setting in the document header, which would override the same setting in the project file.

6.2 When to Use Each Location

6.2.1 1. Project-Level YAML (`_quarto.yml`)

Use the project YAML file for: - Settings that should apply across multiple documents - Default configurations for your project - Consistent styling across documents - Standard execution parameters

Example _quarto.yml:

execute:
  echo: true          # Show code by default
  warning: false      # Hide warnings by default
  message: false      # Hide messages by default
  
format:
  html:
    code-fold: true   # Enable code folding
    toc: true         # Include table of contents
    fig-width: 8      # Default figure width
    fig-height: 6     # Default figure height

6.2.2 2. Document YAML Header

Use the document header for: - Document-specific metadata (title, author, date) - Settings that should apply to the entire document but differ from project defaults - Document-specific output formats or styling - Settings that override project defaults for this specific document

Example document header:

---
title: "Analysis Report"
author: "Jane Smith"
date: today
execute:
  echo: false        # Override project setting to hide code
format:
  html:
    code-fold: false # Override project setting for code folding
    toc-depth: 3     # Specific to this document
---

6.2.3 3. Code Chunk Options

Use code chunk YAML for:

- Chunk-specific behavior that differs from document/project defaults

- Figure-specific settings

- Table formatting for specific outputs

- One-off execution parameters

7 Common Code Chunk Options

7.1 Execution Control

7.2 Figure Control

7.3 Output Control

7.4 Best Practices

Project-Level Settings
- Use for consistent, project-wide defaults
- Keep styling consistent across documents
- Set common execution parameters
- Define shared resources (bibliography, etc.)
Document-Level Settings
- Use for document-specific metadata
- Override project defaults when needed
- Set document-specific formatting
- Define document-specific execution parameters
Code Chunk Settings
- Use for chunk-specific behavior
- Override document/project defaults only when needed
- Keep options close to the code they affect
- Use labels for important chunks
General Guidelines
- Don’t repeat settings unnecessarily
- Use the most specific location needed
- Document significant deviations from defaults
- Use consistent naming conventions for chunks

8 Troubleshooting Tips

Common YAML Errors:
- Inconsistent indentation
- Missing colons after keys
- Incorrect boolean values (use true/false, not True/False)
- Missing quotes around strings containing special characters
Debug Process:
- Use YAML validators
- Check indentation
- Verify all keys are valid Quarto options
- Test changes incrementally

9 Next Steps

After mastering these basics, consider exploring: - Custom CSS/SCSS styling - JavaScript functionality - Advanced PDF customization - Complex cross-referencing - Custom extensions

Remember to consult the Quarto documentation for the most up-to-date options and features.