The Quarto YAML Header

Understand the Quarto YAML header: title, author, date, output format, table of contents, theme and code folding — the settings block that controls your whole document.

Every Quarto document opens with a YAML header: a block fenced by three dashes --- that holds the document’s settings. It’s the control panel — change one line here and the whole output changes. YAML is just key: value pairs, with indentation showing structure.

A typical header

---
title: "Monthly Sales Report"
author: "Analytics Team"
date: today
format:
  html:
    toc: true
    theme: cosmo
    code-fold: true
---

Reading it line by line:

title, author, date — printed at the top of the document. date: today fills in the render date automatically.
format: — the output type. Here it’s html, with its own indented settings underneath.
toc: true — generate a table of contents from your headings.
theme: cosmo — one of 25+ built-in Bootstrap themes (this very site uses cosmo).
code-fold: true — hide code behind a “Show the code” toggle, so readers see results first.

One source, many formats

The same document can target different outputs — just list them under format::

---
title: "Report"
format:
  html: default
  pdf: default
  docx: default
---

Now quarto render produces report.html, report.pdf and report.docx from one source. See the publishing lesson and the post one source, three deliverables.

Watch your indentation

YAML is picky about spaces. Two rules save most headaches:

Indent with spaces, never tabs.
Settings for a format go indented beneath it — toc under html:, not at the left margin.

If a render fails with a confusing YAML error, a misaligned space is the usual culprit. For a field-by-field tour, see the Quarto YAML header explained.

Next: Figures, tables & cross-references → — number and reference your outputs.