Quarto

---
name: quarto-authoring
description: Use when the user is explicitly working with Quarto, .qmd files,
  _quarto.yml, Quarto projects, or Quarto features such as callouts,
  cross-references, citations, Mermaid diagrams, extensions, websites, books,
  presentations, and reports. Also use for explicit migration from or comparison
  with R Markdown, bookdown, blogdown, xaringan, distill, or Jupyter notebooks
  to Quarto. Do not use for general R Markdown or related-format questions
  unless Quarto or migration to Quarto is explicitly mentioned.
metadata:
  author: Mickaël Canouil (@mcanouil)
  version: "1.4"
license: MIT
---

# Quarto Authoring

> This skill is based on Quarto CLI v1.9.36 (2026-03-24).

## When to Use What

Task: Write a new Quarto document Use: Follow "QMD Essentials" below, then see
specific reference files

Task: Add cross-references Use:
[references/cross-references.md](references/cross-references.md)

Task: Configure code cells Use:
[references/code-cells.md](references/code-cells.md)

Task: Add figures with captions Use:
[references/figures.md](references/figures.md)

Task: Create tables Use: [references/tables.md](references/tables.md)

Task: Add citations and bibliography Use:
[references/citations.md](references/citations.md)

Task: Add callout blocks Use: [references/callouts.md](references/callouts.md)

Task: Add diagrams (Mermaid, Graphviz) Use:
[references/diagrams.md](references/diagrams.md)

Task: Control page layout Use: [references/layout.md](references/layout.md)

Task: Use shortcodes Use: [references/shortcodes.md](references/shortcodes.md)

Task: Add conditional content Use:
[references/conditional-content.md](references/conditional-content.md)

Task: Use divs and spans Use:
[references/divs-and-spans.md](references/divs-and-spans.md)

Task: Configure YAML front matter Use:
[references/yaml-front-matter.md](references/yaml-front-matter.md)

Task: Find and use extensions Use:
[references/extensions.md](references/extensions.md)

Task: Apply markdown linting rules Use:
[references/markdown-linting.md](references/markdown-linting.md)

Task: Choose or configure a compute engine (knitr, jupyter, julia) Use:
[references/engines.md](references/engines.md)

### Migration (only when converting an existing project)

Do NOT read these references when writing new Quarto documents. Only read the
one matching the source format when the user explicitly asks to convert or
migrate an existing project.

- R Markdown (.Rmd) to Quarto:
  [references/conversion-rmarkdown.md](references/conversion-rmarkdown.md)
- bookdown project:
  [references/conversion-bookdown.md](references/conversion-bookdown.md)
- xaringan slides:
  [references/conversion-xaringan.md](references/conversion-xaringan.md)
- distill article:
  [references/conversion-distill.md](references/conversion-distill.md)
- blogdown site:
  [references/conversion-blogdown.md](references/conversion-blogdown.md)
- Jupyter notebook (.ipynb) to/from Quarto:
  [references/conversion-jupyter.md](references/conversion-jupyter.md)

## QMD Essentials

### Basic Document Structure

```markdown
---
title: "Document Title"
author: "Author Name"
date: today
format: html
---

Content goes here.
```

A Quarto document consists of two main parts:

1. **YAML Front Matter**: Metadata and configuration at the top, enclosed by
   `---`.
2. **Markdown Content**: Main body using standard markdown syntax.

### Divs and Spans

Divs use fenced syntax with three colons:

```markdown
::: {.class-name}
Content inside the div.
:::
```

Spans use bracketed syntax:

```markdown
This is [important text]{.highlight}.
```

Details: [references/divs-and-spans.md](references/divs-and-spans.md)

### Code Cell Options Syntax

A code cell starts with triple backticks and a language identifier between curly
braces. Code cells are code blocks that can be executed to produce output.

Quarto uses the language's comment symbol + `|` for cell options. Options use
**dashes, not dots** (e.g., `fig-cap` not `fig.cap`).

- R, Python, Julia: `#|`
- Mermaid: `%%|`
- Graphviz/DOT: `//|`

````markdown
```{language}
#| label: fig-example
#| echo: false
#| fig-cap: "A scatter plot example."

# code that produces a figure
```
````

Set document-level defaults in YAML front matter:

```yaml
execute:
  echo: false
  warning: false
```

**Caching --- critical engine difference:** Only suggest `#| cache: true` for R
code cells (knitr engine). Never suggest it for other language cells --- it does
not work and will be silently ignored. The only correct approach is
`execute: cache: true` in the top-level YAML front matter when using engines
other than `knitr`. Python/Jupyter requires `jupyter-cache`
(`pip install jupyter-cache`):

```yaml
execute:
  cache: true
```

Details: [references/code-cells.md](references/code-cells.md)

### Cross-References

Labels must start with a type prefix. Reference with `@`:

- Figure: `fig-` prefix, e.g., `#| label: fig-plot` → `@fig-plot`
- Table: `tbl-` prefix, e.g., `#| label: tbl-data` → `@tbl-data`
- Section: `sec-` prefix, e.g., `{#sec-intro}` → `@sec-intro`
- Equation: `eq-` prefix, e.g., `{#eq-model}` → `@eq-model`

````markdown
```{language}
#| label: fig-plot
#| fig-cap: "A caption for the plot."

# code that produces a figure
```

See @fig-plot for the results.
````

Details: [references/cross-references.md](references/cross-references.md)

### Callout Blocks

Five types: `note`, `warning`, `important`, `tip`, `caution`.

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

::: {.callout-warning}

## Custom Title

This is a warning with a custom title.

:::
```

Details: [references/callouts.md](references/callouts.md)

### Figures

```markdown
![Caption text](image.png){#fig-name fig-alt="Alt text"}
```

Subfigures:

```markdown
::: {#fig-group layout-ncol=2}
![Sub caption 1](image1.png){#fig-sub1}

![Sub caption 2](image2.png){#fig-sub2}

Main caption for the group.
:::
```

Details: [references/figures.md](references/figures.md)

### Tables

```markdown
::: {#tbl-example}

| Column 1 | Column 2 |
| -------- | -------- |
| Data 1   | Data 2   |

Table caption.
:::
```

Details: [references/tables.md](references/tables.md)

### Citations

```markdown
According to @smith2020, the results show...
Multiple citations [@smith2020; @jones2021].
```

Configure in YAML:

```yaml
bibliography: references.bib
csl: apa.csl
```

Details: [references/citations.md](references/citations.md)

## Common Workflows

### Creating an HTML Document

```yaml
title: "My Report"
author: "Your Name"
date: today
format:
  html:
    toc: true
    code-fold: true
    theme: cosmo
```

### Creating a PDF Document

```yaml
title: "My Report"
format:
  pdf:
    documentclass: article
    papersize: a4
```

### Creating a RevealJS Presentation

```markdown
---
title: "My Presentation"
format: revealjs
---

## First Slide

Content here.

## Second Slide

More content.
```

### Setting Up a Quarto Project

Create `_quarto.yml` in the project root:

```yaml
project:
  type: website

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

format:
  html:
    theme: cosmo
```

## Workflow

### Creating a New Document

1. **Choose Template**: Select appropriate template from assets/
2. **Set Metadata**: Configure title, author, date in YAML
3. **Select Format**: Choose HTML or Typst (or both)
4. **Add Content**: Write markdown and code chunks
5. **Render**: Run `quarto render document.qmd`

### Using the Template Script

Generate a new Quarto document:

```bash
uv run python .claude/skills/quarto/scripts/create_quarto.py \
  --output path/to/document.qmd \
  --title "My Analysis" \
  --author "Author Name" \
  --format html \
  --template analysis
```

Template types:

- `analysis` - Data analysis with code chunks
- `report` - Formal report structure
- `presentation` - Slide deck (revealjs)
- `article` - Academic article format

### Rendering Documents

Render to default format:

```bash
quarto render document.qmd
```

Render to specific format:

```bash
quarto render document.qmd --to html
quarto render document.qmd --to typst
```

Render to all formats:

```bash
quarto render document.qmd --to all
```

Preview with live reload:

```bash
quarto preview document.qmd
```

## Resources

- [Quarto Documentation](https://quarto.org/docs/)
- [Quarto Guide](https://quarto.org/docs/guide/)
- [Quarto Extensions](https://quarto.org/docs/extensions/)
- [Community Extensions List](https://m.canouil.dev/quarto-extensions/)