The Quarto YAML header, explained field by field
Every Quarto document opens with a YAML header — the block between two lines of ---. It’s the document’s control panel: change a line here and the whole output changes. Here’s what actually goes in it.
The essentials
---
title: "Monthly Sales Report"
author: "Analytics Team"
date: today
format: html
---title,author— printed at the top of the rendered document.date: today— fills in the render date automatically; you can also write a fixed2026-07-08.format— the output type:html,pdf,docx,revealjs(slides),typst, and more.
Format options
Most of the tuning lives under the format, indented one level:
---
format:
html:
toc: true
number-sections: true
theme: cosmo
code-fold: true
fig-width: 7
---toc: true— build a table of contents from your headings.number-sections: true— number the headings.theme— one of 25+ built-in Bootstrap themes.code-fold: true— hide code behind a “Show the code” toggle so readers see results first.fig-width/fig-height— default figure size in inches.
Execution and parameters
Two blocks you’ll meet often. execute sets document-wide chunk behaviour; params declares inputs for parameterised reports:
---
execute:
echo: false
warning: false
params:
region: "West"
year: 2024
---Here every chunk hides its code and warnings by default, and params$region / params$year are available throughout the document.
Multiple outputs at once
List several formats and one render builds them all:
---
format:
html: default
pdf: default
docx: default
---The one rule that prevents most errors
YAML is picky about whitespace. Indent with spaces, never tabs, and keep a format’s settings indented beneath it — toc under html:, not at the left margin. If a render fails with a cryptic YAML message, a misaligned space is almost always the cause.
Want the interactive version? Work through the YAML header lesson in our free Learn Quarto course.
Need a report template your whole team can render on demand? That’s what we build.