Skip to content
Skills Library
Data & analytics · Writing

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

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 31.08.2026, without references to retired models or APIs.

Licence

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. 1. Block Structure (Fenced Divs)
  2. 2. Cross-Referencing (Strict)
  3. 3. Code Blocks & Execution
  4. 4. Diagrams (Mermaid)
  5. 5. Metadata & Configuration (YAML)
  6. 6. Shortcodes (Special Features)
  7. 7. Citations & Bibliography
  8. 8. Raw Format Blocks
  9. 9. Inline Spans
  10. Anti-Patterns
Original SKILL.md headings · 435 lines, 1,611 words
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}
![Wide figure](wide.png)
:::
```

---

## 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
![System Architecture Diagram](images/arch.png){#fig-arch}
```

**Subfigures** use a parent div with `layout-ncol`:

```markdown
::: {#fig-panels layout-ncol=2}

![First](a.png){#fig-first}

![Second](b.png){#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

RepositoryScoreLicence
This page · nrdxp/predicate100MIT
zengtianli/cc-configs96MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.