YAML Headers in Quarto

Short Introduction

YAML is the metadata block at the top of a Quarto document. It sits between two lines of --- and controls document information such as title, author, date, output formats, and execution settings.

From Plain Note to Configured Publication

The header is only a few lines, but it decides what your document becomes. Because it sits separately from your writing, you can turn the same text into a webpage, a PDF, or a slide deck by changing the header alone, without touching a word of your content.

Basic Example

---
title: "Fieldwork Notes"
author: "A. Researcher"
date: today
format: html
---

How YAML Is Written

YAML is a list of settings, one per line, written as key: value:

the key is the setting name, such as title or format
the value is what you assign to it, such as "Fieldwork Notes" or html

Some settings group several values underneath them. You create that grouping by indenting the lines below with spaces, as with the multiple formats in the example further down. Because the indentation is what defines the grouping, it has to be consistent.

What YAML Usually Controls

Document Metadata

This includes the title, subtitle, authors, date, and sometimes affiliations or keywords.

Output Format

This tells Quarto what to create, such as HTML, PDF, DOCX, or revealjs slides.

Execution Defaults

This controls how code chunks behave across the file, for example whether code is shown or whether warnings are hidden:

execute:
  echo: false
  warning: false

This hides the code and any warnings across the whole document, so the output shows only the results.

Concrete Academic Example

A manuscript draft might use a header like this:

---
title: "How Soil Moisture Shapes Restoration Outcomes"
author:
  - "Research Team"
format:
  html: default
  docx: default
  pdf: default
bibliography: references.bib
---

That one header already signals a multi-format (html, docx, and pdf) workflow.

Common beginner issue

YAML is sensitive to indentation. If spacing is inconsistent, rendering can fail even when the content looks almost correct.

YAML vs Markdown vs Code Chunks

YAML configures the document
Markdown writes the document
code chunks generate results inside the document

Keeping these roles separate makes Quarto much easier to understand.

Next Step

Continue to Installing Quarto for a practical overview of what you need on your machine.