quarto-authoring

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

Task: Configure code cells Use: references/code-cells.md

Task: Add figures with captions Use: references/figures.md

Task: Create tables Use: references/tables.md

Task: Add citations and bibliography Use: references/citations.md

Task: Add callout blocks Use: references/callouts.md

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

Task: Control page layout Use: references/layout.md

Task: Use shortcodes Use: references/shortcodes.md

Task: Add conditional content Use: references/conditional-content.md

Task: Use divs and spans Use: references/divs-and-spans.md

Task: Configure YAML front matter Use: references/yaml-front-matter.md

Task: Find and use extensions Use: references/extensions.md

Task: Apply markdown linting rules Use: references/markdown-linting.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
bookdown project: references/conversion-bookdown.md
xaringan slides: references/conversion-xaringan.md
distill article: references/conversion-distill.md
blogdown site: references/conversion-blogdown.md

QMD Essentials

Basic Document Structure

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

Content goes here.

A Quarto document consists of two main parts:

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

Divs and Spans

Divs use fenced syntax with three colons:

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

Spans use bracketed syntax:

This is [important text]{.highlight}.

Details: 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: #|
Mermaid: %%|
Graphviz/DOT: //|

#| label: fig-example
#| echo: false
#| fig-cap: "A scatter plot example."

plot(x, y)

Common execution options:

Option Description Values

eval

Evaluate code true , false

echo

Show code true , false , fenced

output

Include output true , false , asis

warning

Show warnings true , false

error

Show errors true , false

include

Include in output true , false

Set document-level defaults in YAML front matter:

execute: echo: false warning: false

Details: 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

#| label: fig-plot
#| fig-cap: "A caption for the plot."
plot(1)

See @fig-plot for the results.

Details: references/cross-references.md

Callout Blocks

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

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

::: {.callout-warning}

Custom Title

This is a warning with a custom title.

:::

Details: references/callouts.md

Figures

Caption text {#fig-name fig-alt="Alt text"}

Subfigures:

::: {#fig-group layout-ncol=2} Sub caption 1 {#fig-sub1}

Sub caption 2 {#fig-sub2}

Main caption for the group. :::

Details: references/figures.md

Tables

::: {#tbl-example}

Column 1	Column 2
Data 1	Data 2

Table caption. :::

Details: references/tables.md

Citations

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

Configure in YAML:

bibliography: references.bib csl: apa.csl

Details: references/citations.md

Common Workflows

Creating an HTML Document

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