📘 👨‍💻 📄 YAML in Quarto: The Invisible Heart of Your Documents

programming

YAML

Quarto

article

YAML is the first thing that appears in a .qmd document — but for many, it’s also the most mysterious.

Author

Blog do Marcellini

Published

June 29, 2025

← Back to the Programming Reading Guide 👨‍💻

← Back to the Quarto Section 📄

← Back to the Programming Section 👨‍💻

1 📘 👨‍💻 📄 YAML in Quarto: The Invisible Heart of Your Documents

1.1 Introduction

YAML is the first thing that appears in a .qmd document — but for many, it’s also the most mysterious.

In this post, we will understand:

What YAML is

How it works in .qmd files

Main fields used in Quarto projects

Practical examples of YAML headers

1.2 What is YAML?

YAML stands for “YAML Ain’t Markup Language” — even though it looks like one.

It is a human-readable format used to declare configurations.
It is simple, indented with spaces (not tabs), and uses key:value pairs.

1.3 Minimal example

---
title: "My Document"
author: "Blog do Marcellini"
format: html
---

1.4 Where is YAML Used in Quarto?

At the top of any .qmd file, between --- and ---.

YAML defines how the document will be processed and rendered: title, author, output format, code execution options, cover image, table of contents, and much more.

1.5 Common YAML Fields in Quarto

Field	Description
`title`	Document title
`author`	Name of the author(s)
`date`	Creation or publication date
`format`	Output format: `html`, `pdf`, `epub`, `docx`
`editor`	Type of editor used (e.g., `visual`)
`lang`	Document language (e.g., `en-US`)
`cover-image`	Cover used for EPUB or PDF
`toc`	Shows the table of contents (`true` or `false`)
`execute`	Rules for code execution

1.6 Complete Example

---
title: "Data Analysis with R"
author: "Blog do Marcellini"
date: 2025-06-23
format: html
lang: en-US
toc: true
execute:
  engine: knitr
  echo: true
  warning: false
  message: false
---

1.7 Cautions When Using YAML

✅ Use spaces, never TABs.
✅ Indentation must be consistent.
✅ Lists are created with - item.
✅ Long text blocks can use | (to keep line breaks) or > (to join lines).

1.8 Conclusion

YAML may seem like just a technical block at the beginning of a .qmd, but it is the soul of configuration in Quarto.
Mastering YAML is essential for customizing your documents, projects, websites, and books.

← Back to the Programming Reading Guide 👨‍💻

← Back to the Quarto Section 📄

← Back to the Programming Section 👨‍💻

🔝 Back to Top

Blog do Marcellini — Exploring Mathematics, Statistics, and Physics with Rigor and Beauty.