quarto
/quarto
Formatting, structure, and execution rules for Quarto markdown documents. Trigger when: - Writing, editing, or rendering Quarto documents, reports, presentations, or websites. - Files matching the pattern **/*.qmd are in the workspace or referenced. - Tasks involve: quarto render, quarto preview, knitr, jupyter. - Prompt contains keywords: quarto, qmd, yaml header, code chunk, callout, cross-reference.
- Author
- nrdxp ↗
- Repository
- predicate ↗
- Licence
- MIT
- Last repository change
- 31.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 31.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Formatting, structure, and execution rules for Quarto markdown documents. Trigger when: - Writing, editing, or rendering Quarto documents, reports, presentations, or websites. - Files matching the pattern **/*.qmd are in the workspace or referenced. - Tasks involve: quarto render, quarto preview, knitr, jupyter. - Prompt contains keywords: quarto, qmd, yaml header, code chunk, callout, cross-reference.
Original author description
Formatting, structure, and execution rules for Quarto markdown documents. Trigger when: - Writing, editing, or rendering Quarto documents, reports, presentations, or websites. - Files matching the pattern **/*.qmd are in the workspace or referenced. - Tasks involve: quarto render, quarto preview, knitr, jupyter. - Prompt contains keywords: quarto, qmd, yaml header, code chunk, callout, cross-reference.
How it works
- 1. Block Structure (Fenced Divs)
- 2. Cross-Referencing (Strict)
- 3. Code Blocks & Execution
- 4. Diagrams (Mermaid)
- 5. Metadata & Configuration (YAML)
- 6. Shortcodes (Special Features)
- 7. Citations & Bibliography
- 8. Raw Format Blocks
- 9. Inline Spans
- Anti-Patterns
SKILL.md preview
---
name: quarto
description: |
Formatting, structure, and execution rules for Quarto markdown documents.
Trigger when:
- Writing, editing, or rendering Quarto documents, reports, presentations, or websites.
- Files matching the pattern **/*.qmd are in the workspace or referenced.
- Tasks involve: quarto render, quarto preview, knitr, jupyter.
- Prompt contains keywords: quarto, qmd, yaml header, code chunk, callout, cross-reference.
---
# Quarto (.qmd) Authoring Rules
Quarto is a superset of Pandoc Markdown. It prioritizes semantic structure over visual formatting.
> **Golden Rule:** Never use raw HTML tags (`<div>`, `<img>`, `<br>`) unless absolutely necessary. Use Pandoc Fenced Divs and Spans.
> **Official Documentation:** [quarto.org/docs](https://quarto.org/docs/) is the authoritative reference. Consult it for edge cases, advanced features, or when this skill lacks specifics.
---
## 1. Block Structure (Fenced Divs)
Quarto uses **Fenced Divs** (`:::`) to define layout, callouts, and structural blocks. More colons (`:::::`) enable nesting.
### Callouts (Alerts)
Convert standard Markdown blockquotes (`>`) into semantic callouts.
| Type | Syntax | Use Case |
| :------------ | :------------------------- | :--------------------------- |
| **Note** | `::: {.callout-note}` | Non-critical info |
| **Tip** | `::: {.callout-tip}` | Best practices/optimizations |
| **Important** | `::: {.callout-important}` | Key constraints |
| **Warning** | `::: {.callout-warning}` | Failure modes |
| **Caution** | `::: {.callout-caution}` | Data loss risks |
**Features:**
- **Title:** Use a `##` heading inside, or the `title="..."` attribute.
- **Collapse:** Add `collapse="true"` for expandable callouts (collapsed by default).
- **Appearance:** `appearance="simple"` or `appearance="minimal"` for alternate styles.
- **Icons:** `icon=false` to suppress the default icon.
```markdown
::: {.callout-caution collapse="true" appearance="simple"}
## Warning Title
Collapsible content.
:::
```
### Multi-Column Layouts
Do not use HTML tables or CSS grids for layout. Use Quarto layout divs.
```markdown
:::: {.columns}
::: {.column width="40%"}
Left content (e.g., text)
:::
::: {.column width="60%"}
Right content (e.g., image or code)
:::
::::
```
### Tabsets
Group content into switchable tabs using the `.panel-tabset` class.
```markdown
::: {.panel-tabset}
## Python
Python code here...
## R
R code here...
:::
```
### Layout Classes
Control content width using column classes:
| Class | Width |
| ---------------- | -------------------------------- |
| `.column-body` | Default text column |
| `.column-page` | Extends into page margins |
| `.column-screen` | Full viewport width |
| `.column-margin` | Right margin (for notes, asides) |
```markdown
::: {.column-margin}
This appears in the margin.
:::
::: {.column-page}

:::
```
---
## 2. Cross-Referencing (Strict)
Quarto requires specific ID prefixes for automatic numbering. **Do not manually number sections, figures, or tables.**
### The Prefix Rule
You **MUST** use these prefixes in curly braces `{#...}` to enable referencing:
| Element | Prefix | Example ID | Reference Syntax |
| ---------------- | ------ | --------------- | ---------------- |
| **Figures** | `fig-` | `{#fig-arch}` | `@fig-arch` |
| **Tables** | `tbl-` | `{#tbl-stats}` | `@tbl-stats` |
| **Sections** | `sec-` | `{#sec-deploy}` | `@sec-deploy` |
| **Equations** | `eq-` | `{#eq-perf}` | `@eq-perf` |
| **Listings** | `lst-` | `{#lst-main}` | `@lst-main` |
| **Theorems** | `thm-` | `{#thm-main}` | `@thm-main` |
| **Lemmas** | `lem-` | `{#lem-helper}` | `@lem-helper` |
| **Corollaries** | `cor-` | `{#cor-result}` | `@cor-result` |
| **Propositions** | `prp-` | `{#prp-claim}` | `@prp-claim` |
| **Conjectures** | `cnj-` | `{#cnj-open}` | `@cnj-open` |
| **Definitions** | `def-` | `{#def-term}` | `@def-term` |
| **Examples** | `exm-` | `{#exm-basic}` | `@exm-basic` |
| **Exercises** | `exr-` | `{#exr-prob1}` | `@exr-prob1` |
| **Solutions** | `sol-` | `{#sol-ans}` | `@sol-ans` |
| **Algorithms** | `alg-` | `{#alg-sort}` | `@alg-sort` |
> **LaTeX Warning:** Avoid underscores (`_`) in IDs. They cause issues when rendering to PDF.
**Reserved Prefixes (full list):** `fig`, `tbl`, `lst`, `tip`, `nte`, `wrn`, `imp`, `cau`, `thm`, `lem`, `cor`, `prp`, `cnj`, `def`, `exm`, `exr`, `sol`, `rem`, `alg`, `eq`, `sec`
**Wrong:** `See [Figure 1](#figure-1)`
**Right:** `See @fig-arch`
### Figure Syntax
Images require an ID and a caption (the alt text) to be treated as a Figure.
```markdown
{#fig-arch}
```
**Subfigures** use a parent div with `layout-ncol`:
```markdown
::: {#fig-panels layout-ncol=2}
{#fig-first}
{#fig-second}
Panel caption here.
:::
```
### Table Syntax
Tables must have a caption definition (`: ...`) and an ID to be referenceable.
```markdown
| Component | Status |
| :-------- | :----- |
| API | Stable |
: System Status {#tbl-status}
```
**Column Widths:** Use `tbl-colwidths` to control proportions:
```markdown
: Caption {#tbl-id tbl-colwidths="[60,40]"}
```
### Grid Tables
For complex cells (lists, code blocks, multiple paragraphs), use grid tables:
```markdown
+---------------+---------------+
| Fruit | Advantages |
+===============+===============+
| Bananas | - Portable |
| | - Bright |
+---------------+---------------+
| Oranges | - Vitamin C |
| | - Tasty |
+---------------+---------------+
: Grid table with lists {#tbl-grid}
```
---
## 3. Code Blocks & Execution
Distinguish between **Display Code** and **Executable Code**.
### Display Only (Standard Markdown)
Use standard triple backticks for static snippets.
````markdown
```rust
fn main() { ... }
```
````
### Executable Code (Computation)
Use curly braces `{python}` to indicate the engine should execute the block. Use hash-pipes `#|` for options.
````markdown
```{python}
#| label: fig-plot
#| fig-cap: "Performance metrics"
#| echo: false
import matplotlib.pyplot as plt
plt.plot([1,2,3])
```
````
### Execution Options
Options can be set globally (in YAML `execute:` block) or per-cell (with `#|`).
| Option | Values | Effect |
| ----------- | ------------------------- | ------------------------------------------- |
| `eval` | `true`, `false` | Whether to run the code |
| `echo` | `true`, `false`, `fenced` | Show source code in output |
| `output` | `true`, `false`, `asis` | Show/suppress output; `asis` = raw markdown |
| `warning` | `true`, `false` | Show/hide warnings |
| `error` | `true`, `false` | Allow errors (`true` continues on error) |
| `include` | `true`, `false` | Include cell in output at all |
| `code-fold` | `true`, `false`, `show` | Collapsible source code |
---
## 4. Diagrams (Mermaid)
Do not use images for diagrams if they can be defined as code. Quarto renders Mermaid natively.
````markdown
```{mermaid}
%%| label: fig-flow
%%| fig-cap: "Authentication Flow"
sequenceDiagram
User->>API: Request
API-->>User: Response
```
````
---
## 5. Metadata & Configuration (YAML)
### Document Header
Every `.qmd` file should start with YAML frontmatter.
```yaml
---
title: "Technical Specification"
author: "Engineering Team"
date: last-modified
format:
html:
toc: true
number-sections: true
code-fold: true
theme: cosmo
pdf:
toc: true
number-sections: true
---
```
### Global Execution Options
```yaml
execute:
echo: true # Show code by default
warning: false # Hide warnings
freeze: auto # Only re-execute changed documents
```
### Project Configuration (`_quarto.yml`)
For multi-document projects (books, websites):
```yaml
project:
type: book # or: website, manuscript, default
book:
title: "My Book"
chapters:
- index.qmd
- intro.qmd
- part: "Main Content"
chapters:
- chapter1.qmd
- chapter2.qmd
```
---
## 6. Shortcodes (Special Features)
Use Quarto shortcodes `{{< ... >}}` for special elements.
| Shortcode | Purpose |
| ----------------------------------- | -------------------------------------- |
| `{{< pagebreak >}}` | Force a page break (PDF/Docx) |
| `{{< include _file.qmd >}}` | Embed another file (partial) |
| `{{< embed notebook.ipynb#cell >}}` | Embed output from another notebook/qmd |
| `{{< video src >}}` | Embed video players |
| `{{< var version >}}` | Insert variable from `_variables.yml` |
| `{{< meta title >}}` | Insert value from document metadata |
| `{{< env VAR_NAME >}}` | Insert environment variable |
**Include/Embed Rules:**
- Shortcodes must appear on their own line, surrounded by blank lines.
- Use absolute paths from project root for reliability.
---
## 7. Citations & Bibliography
Quarto uses Pandoc citation syntax with a bibliography file.
**YAML Setup:**
```yaml
---
bibliography: references.bib
csl: apa.csl # Optional: citation style
---
```
**Citation Syntax:**
| Syntax | Renders As |
| --------------------- | ------------------------ |
| `[@smith2023]` | (Smith 2023) |
| `@smith2023` | Smith (2023) inline |
| `[@smith2023, p. 42]` | (Smith 2023, p. 42) |
| `[-@smith2023]` | (2023) — suppress author |
| `[@a; @b]` | Multiple citations |
---
## 8. Raw Format Blocks
Embed format-specific content (ignored in other formats):
````markdown
```{=latex}
\begin{center}
LaTeX-only content
\end{center}
```
````
````markdown
```{=html}
<details><summary>HTML-only</summary>Content</details>
```
````
**Inline:** Use `` `\LaTeX`{=latex} `` for inline raw content.
---
## 9. Inline Spans
Apply attributes to inline text using `[text]{.class #id key="value"}`.
```markdown
This is [important text]{.highlight} with inline styling.
```
---
## Anti-Patterns
| Anti-Pattern | Description | Remedy |
| ---------------------- | --------------------------- | ------------------------------------------------ |
| **Raw HTML** | `<div class="alert">` | Use `::: {.callout-note}` |
| **Hardcoded Numbers** | "As seen in Figure 3" | Use "As seen in @fig-xyz" |
| **Manual TOC** | Writing out a list of links | Use `toc: true` in YAML |
| **Remote Images** | Hotlinking images | Download to `/images` or use repo-relative paths |
| **Empty Lines** | Using `<br>` for spacing | Use CSS classes or margin attributes |
| **Underscores in IDs** | `{#my_figure_1}` | Use hyphens: `{#my-figure-1}` |
---
## Migration Checklist (Markdown → Quarto)
1. **Header:** Add YAML frontmatter with `title`, `format`, and `toc`.
2. **Alerts:** Regex replace `> **Note:**` with `::: {.callout-note}` blocks.
3. **Images:** Add `{#fig-name}` to all image links that need captions.
4. **Links:** Convert local section links `[Link](#heading)` to `@sec-heading`.
5. **Diagrams:** Convert static diagram images to `mermaid` blocks where possible.
6. **IDs:** Replace underscores with hyphens in all identifiers.
7. **Tabsets:** Convert manual tab implementations to `::: {.panel-tabset}`.
8. **Citations:** Convert manual citations to `[@key]` with a `.bib` file.
9. **Project:** For multi-file docs, create `_quarto.yml` to define structure.
---
## Output Formats
Quarto supports multiple output formats via the `format:` key:
| Format | Value | Notes |
| ------------ | ---------- | -------------------------------- |
| HTML | `html` | Default, interactive |
| PDF | `pdf` | Requires LaTeX |
| Word | `docx` | MS Word |
| Presentation | `revealjs` | Slides via Reveal.js |
| Book | `book` | Multi-chapter (in `_quarto.yml`) |
| Typst | `typst` | Modern PDF alternative |
```yaml
format:
html: default
pdf:
documentclass: article
revealjs:
theme: dark
```
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · nrdxp/predicate | 100 | MIT |
| zengtianli/cc-configs | 96 | MIT |
Database snapshot: 13.11.2026 · package version 87ed8cf06192 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100quarto-authoring
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… - 90deploy
Render Quarto `.qmd` slides to HTML and sync to `docs/` for GitHub Pages. Use when user says "deploy", "publish the slides", "ship to pages", "push the lecture live", "render and publish", or after Quarto edits that need to go public. NOT for local Quarto render only — use… - 100qa-quarto
对抗式检查 Quarto 与 Beamer 一致性。批评代理比较 Quarto HTML 渲染结果与 Beamer PDF 基准的内容和视觉效果;修复代理实施修改;循环直到 APPROVED,或连续两轮没有新增 CRITICAL/MAJOR,兜底上限 5 轮。用户说 "qa the quarto"、"check parity"、"does the html match the pdf?"、"quarto matches beamer?"、"检查 Quarto 一致性"、"HTML 和 PDF 一致吗",或在一次 translate-to-quarto… - 90translate-to-quarto
把 Beamer `.tex` 讲稿转换成 Quarto RevealJS `.qmd` 镜像,依次提取 TikZ、逐页翻译、转换引文并自动检查 QA 一致性。用户说 "translate to quarto"、"port to revealjs"、"make an html version"、"convert this beamer to quarto"、"mirror this lecture in qmd"、"把 Beamer 转成 Quarto"、"做一个 HTML 版讲稿" 时使用,也适用于准备把 Beamer 幻灯片发布到网上的场景。产出保存在 `Quarto/`。 - 100skill-133
Commit and publish Quarto project to GitHub Pages. Use when the user wants to publish changes to a Quarto book or website. - 100qa-quarto
Adversarial Quarto-vs-Beamer parity QA. A critic agent compares the Quarto HTML render to the Beamer PDF benchmark for content/visual parity; a fixer agent applies fixes; loops until APPROVED or two consecutive rounds turn up nothing new (fallback cap 5 rounds). Use when user…