One plain-text source, many polished outputs
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
What it is
The pitch: why people love it
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 |
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 |
 |
An image |
`x = 5` |
Inline code |
$E = mc^2$ |
Math: \(E = mc^2\) |
The limitation of plain Markdown
Quarto Markdown (.qmd) = Markdown + two additions
If you know Markdown, you already know about 80% of Quarto. Every Markdown cell in this notebook is valid Quarto.
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
.md; Quarto handles both stepsQuarto 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.
.qmd file + renderingA 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| 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 filesquarto install tinytex oncequarto render notebook.ipynb; the YAML goes in a raw cell at the very top (scroll up: this notebook has one).qmdTry it: change format: html to format: docx, re-render, and open the Word file. Same source, different output.
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)- itemtrue / false:, #, @) in quotestitle: "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
- visualizationMost 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.
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) |
execute: sets defaults, cells override themexecute: block = document-wide default behavior for every code cell#| option in a cell = an exception for that one cellexecute: echo: false in the header, #| echo: true in one cellcode-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 |
echo: falsecode-fold: true (clean page, but your work is visible)error: true: your debugging friend
error: true: the render finishes and the error message appears in the page, right where it happened%%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`.Try it
error: true to error: false and re-render: what happens?code-fold: true to false: what changes on the page?theme: flatly to theme: darklyThis 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.
_quarto.yml)_quarto.yml in the project’s root folderproject:
type: website
output-dir: _site
author: "Hoya Saxa"
format:
html:
theme: cosmo
toc: true
execute:
echo: true_metadata.yml)_metadata.yml inside any subfolder of a project--- lines needed)posts/ folder where every post shares settings--- lines at the top of a .qmd (or the first raw cell of an .ipynb)---
title: "Lab 3 Results"
date: 2026-10-22
format:
html:
code-fold: true
execute:
warning: false
---#| options)#| (hash pipe, then a space)```{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 |
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?
| 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 |
theme but did not wipe out toc from the project.
%%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")
```Try it : delete the theme: flatly lines from post.qmd and re-render. Which theme do you get now, and why?
Why projects?
.qmd is great for one report_quarto.yml; Quarto renders all of it togetherProject 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/ |
Ctrl+Shift+P (Cmd+Shift+P on Mac)Quarto: Create Project and press EnterEquivalent terminal command (handy to know, same result):
Golden rule: always open the project root folder in VS Code (File > Open Folder), and run quarto commands from that folder.
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: trueCommon workflow: add a page
projects.qmd with a title in its YAML header- projects.qmd under navbar: left: in _quarto.ymlquarto preview from the project folder; the new page appears in the menuWhat 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.
_metadata.yml level in the wildmy-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 postposts/ with an index.qmd inside; it shows up in the listing automaticallymy-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: scrreprtchapters: list sets the order of the book; a file not listed is not in the bookmethods.qmd, add it to the listquarto render from the wrong folder (must be the project root, or pass the path)_site/ or _book/: they are regenerated on every render, so your edits vanish. Edit the .qmd sources insteadchapters: list_quarto.yml or _metadata.yml (the leading underscore matters)Big ideas
toc, theme, code-fold, and the execute: block (echo, eval, warning, error)_quarto.yml > metadata _metadata.yml > file front matter > cell #|_quarto.yml; create one from VS Code with Quarto: Create ProjectCheat 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
author in _quarto.yml; override it on about.qmdprojects.qmd page and link it in the navbarprojects.qmd that makes a plot; give it a fig-cap and hide its code with echo: falsecode-fold: true and toc: true for the whole site in _quarto.yml_site/index.htmlWhere to learn more: the official guide at quarto.org/docs/guide and the gallery at quarto.org/docs/gallery