# Sanity check: is Quarto installed and on your PATH?
!quarto --versionIntroduction 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
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 |
 |
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
- A YAML header at the top (settings: title, author, output format, …)
- 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
previewis for working;renderis for producing the final files- PDF output needs a LaTeX installation: run
quarto install tinytexonce - 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
- 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.
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: falsein the header,#| echo: truein 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 messageTry it
- Change
error: truetoerror: falseand re-render: what happens? - Change
code-fold: truetofalse: what changes on the page? - Change
theme: flatlytotheme: 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.ymlin 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: trueLevel 2: Metadata / directory (_metadata.yml)
- Where: a file named exactly
_metadata.ymlinside 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: trueLevel 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 |
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 visibleTry 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
.qmdis 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
- Open VS Code
- Open the Command Palette:
Ctrl+Shift+P(Cmd+Shift+Pon Mac) - Type
Quarto: Create Projectand press Enter - Pick a project type (e.g. Website Project)
- Choose the parent folder where it should live, then type a name for the new project folder
- 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-bookGolden 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: trueCommon workflow: add a page
- Create
projects.qmdwith a title in its YAML header - Add
- projects.qmdundernavbar: left:in_quarto.yml - Run
quarto previewfrom 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 anindex.qmdinside; 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 renderfrom 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.qmdsources instead - Creating a new page but forgetting to add it to the navbar or
chapters:list - Misspelling
_quarto.ymlor_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 theexecute: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
- Create a Website project from VS Code
- Set
authorin_quarto.yml; override it onabout.qmd - Add a
projects.qmdpage and link it in the navbar - Add a Python cell to
projects.qmdthat makes a plot; give it afig-capand hide its code withecho: false - Turn on
code-fold: trueandtoc: truefor the whole site in_quarto.yml - 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