| name | quarto-authoring |
| description | Comprehensive guidance for Quarto document authoring. Use this skill when: (1) Writing new Quarto documents (.qmd) with best practices, (2) Understanding Quarto's code cell syntax with hashpipe (#|) options, (3) Setting up cross-references for figures, tables, sections, and equations, (4) Using Quarto-specific markdown features like callouts, divs, and spans, (5) Configuring YAML front matter for documents and projects, (6) Finding and using Quarto extensions.
|
Quarto Authoring
This skill is based on Quarto CLI v1.8.26.
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
Task: Create presentations and speaker notes
Use: references/presentations.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:
//|
```{r}
#| label: fig-example
#| echo: false
#| fig-cap: "A scatter plot example."
#| fig-width: 8
#| fig-height: 6
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
Example:
::: {#fig-plot}
A plot.
A caption for the plot.
:::
See @fig-plot for the results.
```{r}
#| 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
Basic figure with caption:
{#fig-name fig-alt="Alt text"}
Subfigures:
::: {#fig-group layout-ncol=2}
{#fig-sub1}
{#fig-sub2}
Main caption for the group.
:::
Details: references/figures.md
Tables
Pipe table with caption:
::: {#tbl-example}
| Column 1 | Column 2 |
| -------- | -------- |
| Data 1 | Data 2 |
Table caption.
:::
Details: references/tables.md
Citations
Basic syntax:
According to @smith2020, the results show...
Multiple citations [@smith2020; @jones2021].
Parenthetical only [-@smith2020].
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
Creating a PDF Document
title: "My Report"
format:
pdf:
documentclass: article
papersize: a4
Creating a RevealJS Presentation
---
title: "My Presentation"
format: revealjs
---
## First Slide
Content here.
## Second Slide
More content.
::: {.notes}
Speaker notes for this slide.
:::
Details: references/presentations.md
Setting Up a Quarto Project
Create _quarto.yml in the project root:
project:
type: website
website:
title: "My Site"
navbar:
left:
- href: index.qmd
text: Home
- href: about.qmd
text: About
format:
html:
theme: cosmo
Resources
Reference Files
- references/code-cells.md - Hashpipe syntax, execution options, code display
- references/cross-references.md - Labels, prefixes, all reference types
- references/figures.md - Figures, subfigures, layouts, lightbox
- references/tables.md - Pipe tables, grid tables, styling
- references/citations.md - Bibliography, CSL, footnotes
- references/callouts.md - Callout types, appearance, collapsible
- references/diagrams.md - Mermaid, Graphviz/DOT
- references/layout.md - Column classes, margin content
- references/shortcodes.md - Built-in shortcodes
- references/conditional-content.md - Format-specific content
- references/divs-and-spans.md - Fenced divs, spans, raw blocks
- references/yaml-front-matter.md - Document and project YAML
- references/extensions.md - Using and finding extensions
- references/markdown-linting.md - Markdown linting rules for Quarto
- references/presentations.md - Speaker notes, fragments, backgrounds, columns
External Resources
