Quarto Guide for Beginners

Everything you need to know to get started with Quarto

Author

Documentation Team

Published

December 1, 2025

What is Quarto?

Quarto is an open-source scientific and technical publishing system built on Pandoc. It allows you to create dynamic documents that combine:

Narrative text (written in Markdown)
Code (Python, R, Julia, Observable JS)
Code outputs (plots, tables, results)
Equations, citations, cross-references

Think of Quarto as a powerful tool to create everything from simple documents to complex websites, presentations, and books.

Key Benefits

Multiple outputs from one source - Write once, publish to HTML, PDF, Word, PowerPoint
Language agnostic - Works with Python, R, Julia, and more
Reproducible - Code and narrative in the same document
Professional - Publication-quality output

File Types and Formats

Source Files

.qmd Files (Quarto Markdown)

The primary file type for Quarto documents:

---
title: "My Document"
format: html
---

## Introduction

This is a Quarto document with **markdown** formatting.

::: {#59fd9106 .cell execution_count=1}
``` {.python .cell-code}
# You can include code
print("Hello from Python!")

Hello from Python!

:::


#### .ipynb Files (Jupyter Notebooks)

Quarto can directly render Jupyter notebooks:

- Keep your existing notebook workflow
- Add Quarto features through cell metadata
- Render notebooks to any format

#### .md Files (Plain Markdown)

Standard Markdown files can be rendered by Quarto, though they lack code execution capabilities.

### Output Formats

Quarto can generate:

| Format | Extension | Use Case |
|--------|-----------|----------|
| HTML | .html | Websites, interactive documents |
| PDF | .pdf | Print publications, reports |
| Word | .docx | Microsoft Word documents |
| PowerPoint | .pptx | Presentations |
| Reveal.js | .html | Interactive HTML presentations |
| EPUB | .epub | E-books |
| Markdown | .md | GitHub, other platforms |

## Creating Different Types of Documents

### Basic Document

Simplest Quarto document:

```yaml
---
title: "My First Document"
author: "Your Name"
date: today
format: html
---

## Section 1

Content goes here.

Multi-Format Document

Output to multiple formats:

---
title: "Multi-Format Document"
format:
  html:
    toc: true
    code-fold: true
  pdf:
    documentclass: article
  docx:
    reference-doc: template.docx
---

Presentation (PowerPoint)

---
title: "My Presentation"
format:
  pptx:
    slide-level: 2
---

# Section Title

## Slide 1

- First point
- Second point

## Slide 2

More content here.

Important: Level 1 headers (#) create section dividers, Level 2 headers (##) create new slides.

Presentation (Reveal.js)

---
title: "Interactive Presentation"
format:
  revealjs:
    theme: dark
    transition: slide
---

Website/Book

Requires a _quarto.yml configuration file (covered below).

YAML Front Matter

Every .qmd file starts with YAML front matter between --- markers. This controls document behavior.

Essential YAML Options

---
title: "Document Title"           # Required
subtitle: "Optional subtitle"     # Optional
author: "Author Name"             # Optional
date: today                       # or "2024-01-15"
format: html                      # Output format
---

Format-Specific Options

HTML Options

format:
  html:
    toc: true                    # Table of contents
    toc-depth: 3                 # How many header levels
    code-fold: false             # Collapsible code
    code-tools: true             # Code display options
    theme: cosmo                 # Visual theme
    css: styles.css              # Custom CSS

PDF Options

format:
  pdf:
    documentclass: article
    geometry:
      - margin=1in
    toc: true
    number-sections: true

PowerPoint Options

format:
  pptx:
    reference-doc: template.pptx  # Custom template
    slide-level: 2                # Which heading creates slides
    incremental: true             # Bullets appear one by one

The _quarto.yml Configuration File

The _quarto.yml file controls project-level settings for websites and books.

Basic Website Configuration

project:
  type: website

website:
  title: "My Website"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About

Sidebar Navigation

For documentation sites with a sidebar:

website:
  sidebar:
    style: "docked"
    search: true
    contents:
      - href: index.qmd
        text: Welcome
      - section: "Getting Started"
        contents:
          - guide1.qmd
          - guide2.qmd
      - section: "Advanced"
        contents:
          - advanced1.qmd

Adding Files to Navigation

Adding a Single Document

website:
  sidebar:
    contents:
      - href: new-document.qmd
        text: "Display Name"

Adding a Section with Multiple Documents

website:
  sidebar:
    contents:
      - section: "Section Name"
        contents:
          - doc1.qmd
          - doc2.qmd
          - text: "Custom Name"
            href: doc3.qmd

Adding External Links

website:
  sidebar:
    tools:
      - icon: github
        href: https://github.com/your/repo
        text: "GitHub"

Global Format Settings

Apply settings to all documents:

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
    code-copy: true

Working with Code

Code Blocks

```python
# Python code
import pandas as pd
data = pd.read_csv('file.csv')
print(data.head())
```

Executable vs. Non-Executable Code

By default, code blocks in .qmd files are executable. To display code without running:


::: {#2d043cbe .cell execution_count=2}
``` {.python .cell-code}
# This code is shown but not executed
```
:::

Inline Code

Execute code inline: 4

Output: 4

Code Options

#| echo: false        # Hide code, show output
#| eval: false        # Show code, don't run
#| warning: false     # Hide warnings
#| message: false     # Hide messages
#| label: fig-plot    # For cross-references
#| fig-cap: "Caption" # Figure caption

Markdown Essentials

Headers

# Level 1
## Level 2
### Level 3

Text Formatting

**bold**
*italic*
***bold italic***
`code`
~~strikethrough~~

Lists

- Unordered list
- Second item
  - Nested item

1. Ordered list
2. Second item
   1. Nested item

Links and Images

[Link text](https://url.com)

![Image caption](path/to/image.png)

![Figure with options](image.png){#fig-id width=50%}

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

Cross-References

See @fig-plot for details.

![My plot](plot.png){#fig-plot}

See @tbl-results for the data.

| Col 1 | Col 2 |
|-------|-------|
| A     | B     |

: Results {#tbl-results}

Rendering Documents

Command Line

# Render a single document
quarto render document.qmd

# Render to specific format
quarto render document.qmd --to pdf

# Render entire project
quarto render

# Preview with live reload
quarto preview

# Publish
quarto publish gh-pages

From RStudio or VS Code

RStudio: Click the “Render” button
VS Code: Click “Preview” or use the Quarto extension

Render Options

Control rendering in YAML:

execute:
  echo: true      # Show code
  warning: false  # Hide warnings
  error: true     # Show errors
  cache: true     # Cache results

Special Features

Callout Blocks

::: {.callout-note}
This is a note callout.
:::

::: {.callout-warning}
This is a warning!
:::

::: {.callout-important}
This is important information.
:::

Tabsets

::: {.panel-tabset}

## Tab 1
Content for tab 1

## Tab 2
Content for tab 2

:::

Columns Layout

::: {.columns}

::: {.column width="50%"}
Left column content
:::

::: {.column width="50%"}
Right column content
:::

:::

Diagrams (Mermaid)

```{mermaid}
graph LR
  A[Start] --> B[Process]
  B --> C[End]
```

What Quarto Cannot Do

Limitations

No Real-Time Collaboration
- Not like Google Docs
- Use Git for version control instead
Limited WYSIWYG
- Must render to see final output
- Not a visual editor (though RStudio has visual mode)
LaTeX Required for PDF
- Must install LaTeX distribution for PDF output
- Can be large download (several GB)
Code Must Be Installed
- Python/R/Julia must be installed separately
- Need required packages installed
No Dynamic Forms
- Cannot create user input forms in HTML output
- Use Shiny for interactive applications
Processing Speed
- Large projects can be slow to render
- Use caching to speed up
Not a Database
- Cannot query data directly in document
- Must load data first with code
Limited Styling Control
- HTML/CSS knowledge needed for custom designs
- PDF styling requires LaTeX knowledge

Best Practices

Project Organization

my-project/
├── _quarto.yml           # Project config
├── index.qmd             # Homepage
├── guide1.qmd            # Content files
├── guide2.qmd
├── images/               # Images folder
│   ├── logo.png
│   └── diagram.svg
├── data/                 # Data folder
│   └── dataset.csv
├── scripts/              # Helper scripts
│   └── utils.py
└── _site/               # Generated output (don't edit)

File Naming

Use lowercase, hyphens for spaces: my-document.qmd
Be descriptive: serverless-monitoring.qmd not doc1.qmd
Group related files: tutorial-1.qmd, tutorial-2.qmd

YAML Best Practices

---
# Put most important info first
title: "Clear, Descriptive Title"
subtitle: "Helpful subtitle"
author: "Author Name"
date: today

# Group related options
format:
  html:
    toc: true
    theme: cosmo

# Use comments
execute:
  echo: true  # Show code by default
---

Code Best Practices

Use meaningful labels: {#fig-scatter} not {#fig-1}
Set global options in YAML instead of repeating
Cache expensive computations: cache: true
Organize code into separate scripts if complex
Test frequently - render often to catch errors early

Common Issues and Solutions

Issue: “File not found”

Problem: Referenced image or data file not found

Solution: Use relative paths from the .qmd file location

# Good
![Logo](images/logo.png)

# Bad (absolute paths break portability)
![Logo](/Users/name/project/images/logo.png)

Issue: Code not executing

Problem: Code block shown but not running

Solution: Check code block syntax

# Correct (with braces)

::: {#0652faf8 .cell execution_count=3}
``` {.python .cell-code}
print("Hello")
```

::: {.cell-output .cell-output-stdout}
```
Hello
```
:::
:::


# Wrong (no braces - just displays)
```python
print("Hello")
```

Issue: Links not working in rendered site

Problem: Cross-references broken after rendering

Solution: Use .qmd extension in links - Quarto converts automatically

# Correct
[See guide](guide.qmd)

# Incorrect
[See guide](guide.html)

Issue: Changes not showing

Problem: Made changes but don’t see them in preview

Solution: - Refresh browser (hard refresh: Cmd+Shift+R or Ctrl+Shift+R) - Stop and restart quarto preview - Check if file is saved

Issue: Table of contents not showing

Problem: TOC enabled but not visible

Solution: Need at least 2 headers for TOC to appear

---
format:
  html:
    toc: true
---

## First Section
Content

## Second Section
More content

Quick Reference

Common Quarto Commands

quarto render               # Render project
quarto render file.qmd      # Render single file
quarto preview              # Live preview
quarto create project       # New project wizard
quarto check                # Check installation
quarto --help               # Help

Common YAML Settings

title: "Title"
author: "Name"
date: today
format: html
toc: true
number-sections: true
code-fold: true
theme: cosmo

Format Options Quick Reference

# Multiple formats
format:
  html: default
  pdf: default
  docx: default

# Or with options
format:
  html:
    theme: cosmo
  pdf:
    documentclass: article

Next Steps

Learning Resources

Official Docs: https://quarto.org/docs/guide/
Gallery: https://quarto.org/docs/gallery/
Examples: Browse _site/ in this project for rendered examples

Practice Exercises

Create a simple .qmd document with text and headers
Add a code block that creates a simple plot
Render to HTML, PDF, and Word
Create a presentation with 5 slides
Add your document to the website navigation

Getting Help

Summary

Quarto is powerful for creating reproducible, multi-format documents. Key takeaways:

✅ Files: Create .qmd files with YAML + Markdown + Code ✅ Formats: Output to HTML, PDF, Word, PowerPoint, and more ✅ Configuration: Use _quarto.yml for project-level settings ✅ Navigation: Add files to sidebar in _quarto.yml ✅ Rendering: Use quarto render or IDE buttons ✅ Limitations: Know what Quarto can’t do (real-time collab, dynamic forms) ✅ Best Practices: Organize files, use clear names, test often

Ready to create? Start with a simple document and experiment!

--- title: "Quarto Guide for Beginners" subtitle: "Everything you need to know to get started with Quarto" author: "Documentation Team" date: today format: html: toc: true toc-depth: 3 code-fold: false code-tools: true --- ## What is Quarto? **Quarto** is an open-source scientific and technical publishing system built on Pandoc. It allows you to create dynamic documents that combine: - **Narrative text** (written in Markdown) - **Code** (Python, R, Julia, Observable JS) - **Code outputs** (plots, tables, results) - **Equations, citations, cross-references** Think of Quarto as a powerful tool to create everything from simple documents to complex websites, presentations, and books. ### Key Benefits - **Multiple outputs from one source** - Write once, publish to HTML, PDF, Word, PowerPoint - **Language agnostic** - Works with Python, R, Julia, and more - **Reproducible** - Code and narrative in the same document - **Professional** - Publication-quality output ## File Types and Formats ### Source Files #### .qmd Files (Quarto Markdown) The primary file type for Quarto documents: ```markdown --- title: "My Document" format: html --- ## Introduction This is a Quarto document with **markdown** formatting. ```{python} # You can include code print("Hello from Python!") ``` ``` #### .ipynb Files (Jupyter Notebooks) Quarto can directly render Jupyter notebooks: - Keep your existing notebook workflow - Add Quarto features through cell metadata - Render notebooks to any format #### .md Files (Plain Markdown) Standard Markdown files can be rendered by Quarto, though they lack code execution capabilities. ### Output Formats Quarto can generate: | Format | Extension | Use Case | |--------|-----------|----------| | HTML | .html | Websites, interactive documents | | PDF | .pdf | Print publications, reports | | Word | .docx | Microsoft Word documents | | PowerPoint | .pptx | Presentations | | Reveal.js | .html | Interactive HTML presentations | | EPUB | .epub | E-books | | Markdown | .md | GitHub, other platforms | ## Creating Different Types of Documents ### Basic Document Simplest Quarto document: ```yaml --- title: "My First Document" author: "Your Name" date: today format: html --- ## Section 1 Content goes here. ``` ### Multi-Format Document Output to multiple formats: ```yaml --- title: "Multi-Format Document" format: html: toc: true code-fold: true pdf: documentclass: article docx: reference-doc: template.docx --- ``` ### Presentation (PowerPoint) ```yaml --- title: "My Presentation" format: pptx: slide-level: 2 --- # Section Title ## Slide 1 - First point - Second point ## Slide 2 More content here. ``` **Important:** Level 1 headers (`#`) create section dividers, Level 2 headers (`##`) create new slides. ### Presentation (Reveal.js) ```yaml --- title: "Interactive Presentation" format: revealjs: theme: dark transition: slide --- ``` ### Website/Book Requires a `_quarto.yml` configuration file (covered below). ## YAML Front Matter Every `.qmd` file starts with YAML front matter between `---` markers. This controls document behavior. ### Essential YAML Options ```yaml --- title: "Document Title" # Required subtitle: "Optional subtitle" # Optional author: "Author Name" # Optional date: today # or "2024-01-15" format: html # Output format --- ``` ### Format-Specific Options #### HTML Options ```yaml format: html: toc: true # Table of contents toc-depth: 3 # How many header levels code-fold: false # Collapsible code code-tools: true # Code display options theme: cosmo # Visual theme css: styles.css # Custom CSS ``` #### PDF Options ```yaml format: pdf: documentclass: article geometry: - margin=1in toc: true number-sections: true ``` #### PowerPoint Options ```yaml format: pptx: reference-doc: template.pptx # Custom template slide-level: 2 # Which heading creates slides incremental: true # Bullets appear one by one ``` ## The _quarto.yml Configuration File The `_quarto.yml` file controls **project-level settings** for websites and books. ### Basic Website Configuration ```yaml project: type: website website: title: "My Website" navbar: left: - href: index.qmd text: Home - href: about.qmd text: About ``` ### Sidebar Navigation For documentation sites with a sidebar: ```yaml website: sidebar: style: "docked" search: true contents: - href: index.qmd text: Welcome - section: "Getting Started" contents: - guide1.qmd - guide2.qmd - section: "Advanced" contents: - advanced1.qmd ``` ### Adding Files to Navigation #### Adding a Single Document ```yaml website: sidebar: contents: - href: new-document.qmd text: "Display Name" ``` #### Adding a Section with Multiple Documents ```yaml website: sidebar: contents: - section: "Section Name" contents: - doc1.qmd - doc2.qmd - text: "Custom Name" href: doc3.qmd ``` #### Adding External Links ```yaml website: sidebar: tools: - icon: github href: https://github.com/your/repo text: "GitHub" ``` ### Global Format Settings Apply settings to all documents: ```yaml format: html: theme: cosmo css: styles.css toc: true code-copy: true ``` ## Working with Code ### Code Blocks ````markdown ```python # Python code import pandas as pd data = pd.read_csv('file.csv') print(data.head()) ``` ```` ### Executable vs. Non-Executable Code By default, code blocks in `.qmd` files are **executable**. To display code without running: ````markdown ```{python} #| eval: false # This code is shown but not executed ``` ```` ### Inline Code Execute code inline: `` `{python} 2 + 2` `` Output: 4 ### Code Options ```python #| echo: false # Hide code, show output #| eval: false # Show code, don't run #| warning: false # Hide warnings #| message: false # Hide messages #| label: fig-plot # For cross-references #| fig-cap: "Caption" # Figure caption ``` ## Markdown Essentials ### Headers ```markdown # Level 1 ## Level 2 ### Level 3 ``` ### Text Formatting ```markdown **bold** *italic* ***bold italic*** `code` ~~strikethrough~~ ``` ### Lists ```markdown - Unordered list - Second item - Nested item 1. Ordered list 2. Second item 1. Nested item ``` ### Links and Images ```markdown [Link text](https://url.com) ![Image caption](path/to/image.png) ![Figure with options](image.png){#fig-id width=50%} ``` ### Tables ```markdown | Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Data 1 | Data 2 | Data 3 | | Data 4 | Data 5 | Data 6 | ``` ### Cross-References ```markdown See @fig-plot for details. ![My plot](plot.png){#fig-plot} See @tbl-results for the data. | Col 1 | Col 2 | |-------|-------| | A | B | : Results {#tbl-results} ``` ## Rendering Documents ### Command Line ```bash # Render a single document quarto render document.qmd # Render to specific format quarto render document.qmd --to pdf # Render entire project quarto render # Preview with live reload quarto preview # Publish quarto publish gh-pages ``` ### From RStudio or VS Code - **RStudio**: Click the "Render" button - **VS Code**: Click "Preview" or use the Quarto extension ### Render Options Control rendering in YAML: ```yaml execute: echo: true # Show code warning: false # Hide warnings error: true # Show errors cache: true # Cache results ``` ## Special Features ### Callout Blocks ```markdown ::: {.callout-note} This is a note callout. ::: ::: {.callout-warning} This is a warning! ::: ::: {.callout-important} This is important information. ::: ``` ### Tabsets ```markdown ::: {.panel-tabset} ## Tab 1 Content for tab 1 ## Tab 2 Content for tab 2 ::: ``` ### Columns Layout ```markdown ::: {.columns} ::: {.column width="50%"} Left column content ::: ::: {.column width="50%"} Right column content ::: ::: ``` ### Diagrams (Mermaid) ````markdown ```{mermaid} graph LR A[Start] --> B[Process] B --> C[End] ``` ```` ## What Quarto Cannot Do ### Limitations 1. **No Real-Time Collaboration** - Not like Google Docs - Use Git for version control instead 2. **Limited WYSIWYG** - Must render to see final output - Not a visual editor (though RStudio has visual mode) 3. **LaTeX Required for PDF** - Must install LaTeX distribution for PDF output - Can be large download (several GB) 4. **Code Must Be Installed** - Python/R/Julia must be installed separately - Need required packages installed 5. **No Dynamic Forms** - Cannot create user input forms in HTML output - Use Shiny for interactive applications 6. **Processing Speed** - Large projects can be slow to render - Use caching to speed up 7. **Not a Database** - Cannot query data directly in document - Must load data first with code 8. **Limited Styling Control** - HTML/CSS knowledge needed for custom designs - PDF styling requires LaTeX knowledge ## Best Practices ### Project Organization ``` my-project/ ├── _quarto.yml # Project config ├── index.qmd # Homepage ├── guide1.qmd # Content files ├── guide2.qmd ├── images/ # Images folder │ ├── logo.png │ └── diagram.svg ├── data/ # Data folder │ └── dataset.csv ├── scripts/ # Helper scripts │ └── utils.py └── _site/ # Generated output (don't edit) ``` ### File Naming - Use lowercase, hyphens for spaces: `my-document.qmd` - Be descriptive: `serverless-monitoring.qmd` not `doc1.qmd` - Group related files: `tutorial-1.qmd`, `tutorial-2.qmd` ### YAML Best Practices ```yaml --- # Put most important info first title: "Clear, Descriptive Title" subtitle: "Helpful subtitle" author: "Author Name" date: today # Group related options format: html: toc: true theme: cosmo # Use comments execute: echo: true # Show code by default --- ``` ### Code Best Practices 1. **Use meaningful labels**: `{#fig-scatter}` not `{#fig-1}` 2. **Set global options** in YAML instead of repeating 3. **Cache expensive computations**: `cache: true` 4. **Organize code** into separate scripts if complex 5. **Test frequently** - render often to catch errors early ## Common Issues and Solutions ### Issue: "File not found" **Problem:** Referenced image or data file not found **Solution:** Use relative paths from the `.qmd` file location ```markdown # Good ![Logo](images/logo.png) # Bad (absolute paths break portability) ![Logo](/Users/name/project/images/logo.png) ``` ### Issue: Code not executing **Problem:** Code block shown but not running **Solution:** Check code block syntax ````markdown # Correct (with braces) ```{python} print("Hello") ``` # Wrong (no braces - just displays) ```python print("Hello") ``` ```` ### Issue: Links not working in rendered site **Problem:** Cross-references broken after rendering **Solution:** Use `.qmd` extension in links - Quarto converts automatically ```markdown # Correct [See guide](guide.qmd) # Incorrect [See guide](guide.html) ``` ### Issue: Changes not showing **Problem:** Made changes but don't see them in preview **Solution:** - Refresh browser (hard refresh: Cmd+Shift+R or Ctrl+Shift+R) - Stop and restart `quarto preview` - Check if file is saved ### Issue: Table of contents not showing **Problem:** TOC enabled but not visible **Solution:** Need at least 2 headers for TOC to appear ```markdown --- format: html: toc: true --- ## First Section Content ## Second Section More content ``` ## Quick Reference ### Common Quarto Commands ```bash quarto render # Render project quarto render file.qmd # Render single file quarto preview # Live preview quarto create project # New project wizard quarto check # Check installation quarto --help # Help ``` ### Common YAML Settings ```yaml title: "Title" author: "Name" date: today format: html toc: true number-sections: true code-fold: true theme: cosmo ``` ### Format Options Quick Reference ```yaml # Multiple formats format: html: default pdf: default docx: default # Or with options format: html: theme: cosmo pdf: documentclass: article ``` ## Next Steps ### Learning Resources - **Official Docs**: [https://quarto.org/docs/guide/](https://quarto.org/docs/guide/) - **Gallery**: [https://quarto.org/docs/gallery/](https://quarto.org/docs/gallery/) - **Examples**: Browse `_site/` in this project for rendered examples ### Practice Exercises 1. Create a simple `.qmd` document with text and headers 2. Add a code block that creates a simple plot 3. Render to HTML, PDF, and Word 4. Create a presentation with 5 slides 5. Add your document to the website navigation ### Getting Help - Check the [Quarto documentation](https://quarto.org) - Search [GitHub Issues](https://github.com/quarto-dev/quarto-cli/issues) - Ask on [Quarto Discussions](https://github.com/quarto-dev/quarto-cli/discussions) --- ## Summary **Quarto is powerful** for creating reproducible, multi-format documents. Key takeaways: ✅ **Files**: Create `.qmd` files with YAML + Markdown + Code ✅ **Formats**: Output to HTML, PDF, Word, PowerPoint, and more ✅ **Configuration**: Use `_quarto.yml` for project-level settings ✅ **Navigation**: Add files to sidebar in `_quarto.yml` ✅ **Rendering**: Use `quarto render` or IDE buttons ✅ **Limitations**: Know what Quarto can't do (real-time collab, dynamic forms) ✅ **Best Practices**: Organize files, use clear names, test often **Ready to create?** Start with a simple document and experiment!