Introduction to Quarto

One plain-text source, many polished outputs

Introduction to Quarto

Resource: quarto-article-example

Goal for today: by the end of class you can create a Quarto project from VS Code, render it, and know exactly where to put a setting so it applies to the right things.

Part Topic Time
1 Why Quarto?
2 From Markdown to Quarto
3 Anatomy of a .qmd file + rendering
4 YAML crash course
4b The most-used YAML options
5 The four YAML levels
6 Projects: websites, blogs, books
7 Wrap-up and cheat sheet

Before we start

  • You need two things installed (see the setup guide):
    • the Quarto CLI (the actual program)
    • the Quarto extension for VS Code (the editor integration)
  • Follow along in VS Code; run every cell as we go
# Sanity check: is Quarto installed and on your PATH?
!quarto --version

Part 1: Why Quarto?

What it is

  • An open-source publishing system from Posit (the company behind RStudio)
  • You write plain text + code; Quarto produces polished documents
  • Think of it as a compiler for documents: source file in, finished product out

The pitch: why people love it

  • One source, many outputs: the same file becomes an HTML page, a PDF, a Word doc, or a slide deck
  • Code and narrative live together: figures and tables are produced by the code, so they never go stale (no more copy-pasting plots into Word)
  • Language agnostic: Python, R, Julia, and Observable JS; it also renders Jupyter notebooks directly
  • Plain text: readable without special software, and plays perfectly with Git
  • Reproducible: anyone with your files can re-render and get the same report

Who uses it, and for what

Who What they make
Data scientists Analysis reports, dashboards, internal docs
Researchers Papers, lab websites, reproducible manuscripts
Instructors Course websites, lecture slides, notes (including this course)
Authors Free online books (e.g. R for Data Science, 2nd ed.)
Students (you!) A portfolio website showing your projects to employers

Part 2: From Markdown to Quarto

Markdown refresher: a lightweight way to format text with a few symbols.

You type You get
# Heading 1, ## Heading 2 Section headings
**bold**, *italic* bold, italic
- item Bulleted list
1. item Numbered list
[Georgetown](https://georgetown.edu) A link
![caption](figs/plot.png) An image
`x = 5` Inline code
$E = mc^2$ Math: \(E = mc^2\)

The limitation of plain Markdown

  • It is static: it cannot run code
  • Limited control over layout, output format, and styling

Quarto Markdown (.qmd) = Markdown + two additions

  1. A YAML header at the top (settings: title, author, output format, …)
  2. Executable code cells whose results are inserted into the document

If you know Markdown, you already know about 80% of Quarto. Every Markdown cell in this notebook is valid Quarto.

What happens when you click “Render”

report.qmd ──► Jupyter (Python) or knitr (R) ──► report.md ──► Pandoc ──► report.html
                  runs the code, inserts           plain          converts     report.pdf
                  outputs into the text            Markdown       formats      report.docx
  • Step 1: an engine runs your code and pastes the results into ordinary Markdown
  • Step 2: Pandoc (a universal document converter) turns that Markdown into the format you asked for
  • You never touch the intermediate .md; Quarto handles both steps

A taste of Quarto-only Markdown

Quarto adds a few extras on top of standard Markdown. One example, a callout box:

::: {.callout-tip}
## Pro tip
Render early and often. Small errors are easy to find; big ones are not.
:::

Others you will meet later: citations ([@smith2020]), cross-references (@fig-scatter), multi-column layouts.

Part 3: Anatomy of a .qmd file + rendering

A complete, minimal Quarto document has three parts:

---
title: "My First Report"          # <── 1. YAML header (between the --- lines)
author: "Hoya Saxa"
format: html
---

## Introduction                   # <── 2. Markdown body (just normal Markdown)

This report looks at **penguins**.

```{python}                       # <── 3. Executable code cell
#| echo: false
import math
print(math.pi)
```

Watch the braces

  • ```{python} (with braces) means run this code
  • ```python (no braces) means just display this code, do not run it

How to render

Where Action What it does
VS Code Preview button, or Ctrl+Shift+K (Cmd+Shift+K on Mac) Renders and opens a live preview that updates every time you save
Terminal quarto preview report.qmd Same as above, from the command line
Terminal quarto render report.qmd Renders once to the default format, no live preview
Terminal quarto render report.qmd --to pdf Renders to a specific format

Notes

  • preview is for working; render is for producing the final files
  • PDF output needs a LaTeX installation: run quarto install tinytex once
  • Jupyter notebooks work too: quarto render notebook.ipynb; the YAML goes in a raw cell at the very top (scroll up: this notebook has one)

Live demo: write and render a .qmd

%%writefile hello.qmd
---
title: "Hello, Quarto"
author: "Your Name"
format: html
---

## A tiny report

Quarto ran the code below and inserted the result.

```{python}
squares = [n**2 for n in range(1, 6)]
print(squares)
```

The sum of the first five squares is `{python} sum(squares)`.
!quarto render hello.qmd
# Now open hello.html in your browser (or right-click > Open with Live Preview in VS Code)

Try it: change format: html to format: docx, re-render, and open the Word file. Same source, different output.

Part 4: YAML crash course

YAML (“YAML Ain’t Markup Language”) is a human-readable format for settings. Quarto uses it everywhere.

The rules

  • key: value (a space after the colon is required)
  • Nesting is done with indentation: use spaces (2 is standard), never tabs
  • Lists use a dash: - item
  • Booleans: true / false
  • Put text containing special characters (:, #, @) in quotes
title: "Analysis: Part 1"     # quoted because the title contains a colon
author: "Ada Lovelace"
date: today
format:                       # a key whose value is a nested block
  html:
    toc: true                 # indented 4 spaces: belongs to html
    code-fold: true
  pdf: default
bibliography: refs.bib
categories:                   # a list
  - python
  - visualization

Most common YAML errors: no space after a colon (title:"Report"), inconsistent indentation or tabs, and an unquoted colon inside a value (title: Part 1: Intro).

Tip: in VS Code the Quarto extension autocompletes YAML options (Ctrl+Space) and underlines invalid ones. Let it help you.

Part 4b: The most-used YAML options

Quarto has hundreds of options. You will use about fifteen of them almost every day.

Document info (top level)

Option Example Effect
title, subtitle title: "Lab 3" Title block at the top
author author: "Ada Lovelace" Byline (can be a list)
date date: today Date; today fills in the render date

Format and layout (under format: html: and friends)

Option Example Effect
format format: html Output type: html, pdf, docx, revealjs
toc toc: true Table of contents from your headings
toc-depth toc-depth: 2 How many heading levels the TOC shows
number-sections number-sections: true Numbers headings 1, 1.1, 1.2, …
theme theme: cosmo Visual theme (try flatly, darkly, lux)
embed-resources embed-resources: true Packs everything into one shareable .html file

Code display (HTML only, under format: html:)

Option Example Effect
code-fold code-fold: true Code hidden behind a clickable “Code” toggle
code-tools code-tools: true Menu to show/hide all code and view the source
code-line-numbers code-line-numbers: true Line numbers on code blocks

Execution (under execute:)

Option Example Effect
echo echo: false Hide all code, keep outputs (reports for non-coders)
eval eval: false Show code but do not run any of it
warning warning: false Hide warning messages
error error: true Show errors in the output instead of stopping the render
freeze freeze: auto Projects only: re-run code only when its source changed

Figures (top level, or per cell)

Option Example Effect
fig-width, fig-height fig-width: 6 Default figure size in inches
fig-cap fig-cap: "Scores" Caption (usually set per cell)

Key idea: execute: sets defaults, cells override them

  • The execute: block = document-wide default behavior for every code cell
  • A #| option in a cell = an exception for that one cell
  • Same option name in both places: execute: echo: false in the header, #| echo: true in one cell

code-fold vs echo: false: a common confusion

Reader can see the code?
echo: false No, it is gone from the page
code-fold: true Yes, one click away
  • Report for a manager: echo: false
  • Homework or a portfolio: code-fold: true (clean page, but your work is visible)

error: true: your debugging friend

  • Default: one broken cell stops the whole render, and you get no output at all
  • With error: true: the render finishes and the error message appears in the page, right where it happened
  • Use it while drafting; turn it off for the final version so mistakes do not slip through

Live demo: a typical header with these options

%%writefile options-demo.qmd
---
title: "Options Demo"
author: "Your Name"
date: today
format:
  html:
    theme: flatly
    toc: true
    number-sections: true
    code-fold: true
    code-tools: true
    embed-resources: true
execute:
  echo: true
  warning: false
  error: true
---

## Data

```{python}
scores = [72, 85, 90, 64, 88, 95, 78]
print("Mean score:", sum(scores) / len(scores))
```

## A hidden calculation

```{python}
#| echo: false
print("Students above 80:", sum(s > 80 for s in scores))
```

## A broken cell

```{python}
print(scores[100])   # deliberate IndexError
```

The render still finishes because of `error: true`.
!quarto render options-demo.qmd
# Open options-demo.html: find the "Code" toggles, the TOC, the numbered sections, and the error message

Try it

  1. Change error: true to error: false and re-render: what happens?
  2. Change code-fold: true to false: what changes on the page?
  3. Change theme: flatly to theme: darkly

Part 5: The four YAML levels

This is the single most important idea of the day.

Quarto settings can be written at four levels. Each level covers a different scope:

PROJECT    _quarto.yml           applies to every file in the project
 └─ METADATA  _metadata.yml      applies to every file in that folder (and its subfolders)
     └─ FILE    YAML front matter   applies to one document
         └─ CELL  #| options        applies to one code cell

The rule: settings cascade downward, and the closest (most specific) setting wins.

  • Like CSS, or like a company policy: company-wide rule < department rule < your manager’s instruction for this one task
  • Rule of thumb: put a setting at the highest level where it is true for everything below it

Level 1: Project (_quarto.yml)

  • Where: a file named exactly _quarto.yml in the project’s root folder
  • Scope: every document in the project
  • Bonus job: its presence is what makes a folder a Quarto project
  • Typical contents: project type, site navigation, shared theme, default author, execution defaults
project:
  type: website
  output-dir: _site

author: "Hoya Saxa"

format:
  html:
    theme: cosmo
    toc: true

execute:
  echo: true

Level 2: Metadata / directory (_metadata.yml)

  • Where: a file named exactly _metadata.yml inside any subfolder of a project
  • Scope: every document in that folder and its subfolders
  • Same keys as the file-level header (no --- lines needed)
  • Typical use: a posts/ folder where every post shares settings
# posts/_metadata.yml
author: "Data Science Club"
categories:
  - club-news
title-block-banner: true

Level 3: File / document (YAML front matter)

  • Where: between the --- lines at the top of a .qmd (or the first raw cell of an .ipynb)
  • Scope: this one document
  • Typical use: title, date, and anything this file does differently from the rest
---
title: "Lab 3 Results"
date: 2026-10-22
format:
  html:
    code-fold: true
execute:
  warning: false
---

Level 4: Cell (#| options)

  • Where: special comment lines at the top of a code cell, starting with #| (hash pipe, then a space)
  • Scope: this one cell only
  • Typical use: hide this code, caption this figure, skip running this cell
```{python}
#| label: fig-scores
#| fig-cap: "Distribution of exam scores"
#| echo: false
import matplotlib.pyplot as plt
plt.hist([72, 85, 90, 64, 88, 95, 78]);
```

The cell options you will use 90% of the time

Option Effect
echo: false Hide the code, show the output
eval: false Show the code, do not run it
include: false Run it, but show nothing (good for setup/imports)
output: false Show code, hide output
warning: false Hide warning messages
fig-cap: "..." Figure caption
label: fig-name Name for cross-referencing (@fig-name)
code-fold: true Collapse code behind a “Code” toggle

Putting it together: predict the outcome

Imagine this project layout:

my-project/
├── _quarto.yml            author: "Project Author",  theme: cosmo,   toc: true,  echo: true
└── posts/
    ├── _metadata.yml      author: "Folder Author",   theme: darkly
    └── post.qmd           theme: flatly,  echo: false
                             cell A has  #| echo: true
                             cell B has no options

Before scrolling: for post.qmd, what are the author, the theme, the table of contents, and the code visibility of each cell?

Click for the answer
Setting Final value Decided at
author Folder Author Metadata (beats project)
theme flatly File (beats metadata and project)
toc true Project (nobody overrode it)
Cell A code shown Cell (beats file)
Cell B code hidden File
Note that settings merge: the file changed theme but did not wipe out toc from the project.

Live demo: build this exact project and check our prediction

import os
os.makedirs("cascade-demo/posts", exist_ok=True)
%%writefile cascade-demo/_quarto.yml
project:
  title: "Cascade demo"

author: "Project Author"

format:
  html:
    theme: cosmo
    toc: true

execute:
  echo: true
%%writefile cascade-demo/posts/_metadata.yml
author: "Folder Author"
format:
  html:
    theme: darkly
%%writefile cascade-demo/posts/post.qmd
---
title: "Who wins?"
format:
  html:
    theme: flatly
execute:
  echo: false
---

## Cell A

```{python}
#| echo: true
print("Cell A: cell-level echo: true overrides the file's echo: false")
```

## Cell B

```{python}
print("Cell B: follows the file-level setting, so its code is hidden")
```
!quarto render cascade-demo
# Open cascade-demo/posts/post.html: check the author, the theme, the TOC, and which code is visible

Try it : delete the theme: flatly lines from post.qmd and re-render. Which theme do you get now, and why?

Part 6: Projects: websites, blogs, books

Why projects?

  • A single .qmd is great for one report
  • Real work has many files that share settings, navigation, and links between pages
  • A project is simply a folder with a _quarto.yml; Quarto renders all of it together

Project types

Type Use it for Output folder
Default A collection of standalone documents with shared settings next to the sources
Website Portfolio, course site, documentation _site/
Blog A website with dated posts and an automatic listing page _site/
Book Long-form content in ordered chapters (HTML + PDF) _book/
Manuscript A scholarly article with linked notebooks _manuscript/

Creating an empty project shell from VS Code

  1. Open VS Code
  2. Open the Command Palette: Ctrl+Shift+P (Cmd+Shift+P on Mac)
  3. Type Quarto: Create Project and press Enter
  4. Pick a project type (e.g. Website Project)
  5. Choose the parent folder where it should live, then type a name for the new project folder
  6. VS Code opens the new project, already populated with starter files

Equivalent terminal command (handy to know, same result):

quarto create project website my-site
quarto create project book my-book

Golden rule: always open the project root folder in VS Code (File > Open Folder), and run quarto commands from that folder.

Website project: what you get

my-site/
├── _quarto.yml     project settings + navigation bar
├── index.qmd       the home page (index = "front door" of any website)
├── about.qmd       a second page
└── styles.css      optional custom styling

The generated _quarto.yml (yours may differ slightly by version):

project:
  type: website

website:
  title: "my-site"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

Common workflow: add a page

  1. Create projects.qmd with a title in its YAML header
  2. Add - projects.qmd under navbar: left: in _quarto.yml
  3. Run quarto preview from the project folder; the new page appears in the menu

What to deploy: the _site/ folder is a complete, self-contained website (plain HTML/CSS/JS). Copy it to any web host: GitHub Pages, Quarto Pub (quarto publish), Netlify, or your GU Domains space.

Blog project: the _metadata.yml level in the wild

my-blog/
├── _quarto.yml
├── index.qmd           auto-generated listing of all posts
├── about.qmd
└── posts/
    ├── _metadata.yml   shared settings for every post
    ├── welcome/
    │   └── index.qmd
    └── post-with-code/
        └── index.qmd

The starter posts/_metadata.yml looks like this:

# options specified here will apply to all posts in this folder
freeze: true               # do not re-run old posts' code on every render
title-block-banner: true   # banner-style title on every post
  • New post = new folder under posts/ with an index.qmd inside; it shows up in the listing automatically

Book project: what you get

my-book/
├── _quarto.yml
├── index.qmd        preface (the book's front page)
├── intro.qmd        chapter 1
├── summary.qmd      chapter 2
├── references.qmd   bibliography page
├── references.bib   citation database (BibTeX)
└── cover.png

The key part of _quarto.yml:

project:
  type: book

book:
  title: "my-book"
  author: "Jane Doe"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
  • The chapters: list sets the order of the book; a file not listed is not in the book
  • Add a chapter: create methods.qmd, add it to the list
  • One source, two products: an HTML book and a PDF book from the same files

Common project pitfalls

  • Running quarto render from the wrong folder (must be the project root, or pass the path)
  • Editing files inside _site/ or _book/: they are regenerated on every render, so your edits vanish. Edit the .qmd sources instead
  • Creating a new page but forgetting to add it to the navbar or chapters: list
  • Misspelling _quarto.yml or _metadata.yml (the leading underscore matters)

Part 7: Wrap-up

Big ideas

  • Quarto = Markdown + YAML + executable code, rendered by an engine and Pandoc
  • A small set of options does most of the work: toc, theme, code-fold, and the execute: block (echo, eval, warning, error)
  • One source, many outputs: HTML, PDF, Word, slides, websites, books
  • Four YAML levels, closest wins: project _quarto.yml > metadata _metadata.yml > file front matter > cell #|
  • A project is a folder with _quarto.yml; create one from VS Code with Quarto: Create Project

Cheat sheet

Task How
Check install quarto check
Live preview VS Code Preview button, or quarto preview
Render one file quarto render file.qmd
Render to a format quarto render file.qmd --to pdf
Render whole project quarto render (from project root)
New project Command Palette > Quarto: Create Project
Publish quarto publish, or copy _site/ to a web host
Level File / syntax Scope
Project _quarto.yml whole project
Metadata _metadata.yml one folder and below
File --- front matter one document
Cell #| option: value one code cell

Practice before next class

  1. Create a Website project from VS Code
  2. Set author in _quarto.yml; override it on about.qmd
  3. Add a projects.qmd page and link it in the navbar
  4. Add a Python cell to projects.qmd that makes a plot; give it a fig-cap and hide its code with echo: false
  5. Turn on code-fold: true and toc: true for the whole site in _quarto.yml
  6. Render and open _site/index.html

Where to learn more: the official guide at quarto.org/docs/guide and the gallery at quarto.org/docs/gallery