quarto-authoring

Quarto 写作

此技能基于 Quarto CLI v1.9.36（2026-03-24）。

该用什么

任务：编写新的 Quarto 文档 使用：遵循下方的“QMD 基础”，然后查看具体的参考文件

任务：添加交叉引用 使用：references/cross-references.md

任务：配置代码单元格 使用：references/code-cells.md

任务：添加带标题的图 使用：references/figures.md

任务：创建表格 使用：references/tables.md

任务：添加引文和参考文献 使用：references/citations.md

任务：添加提示框 使用：references/callouts.md

任务：添加图表（Mermaid、Graphviz） 使用：references/diagrams.md

任务：控制页面布局 使用：references/layout.md

任务：使用短代码 使用：references/shortcodes.md

任务：添加条件内容 使用：references/conditional-content.md

任务：使用 div 和 span 使用：references/divs-and-spans.md

任务：配置 YAML 前置元数据 使用：references/yaml-front-matter.md

任务：查找和使用扩展 使用：references/extensions.md

任务：应用 Markdown lint 规则 使用：references/markdown-linting.md

任务：选择或配置计算引擎（knitr、jupyter、julia） 使用：references/engines.md

迁移（仅在转换现有项目时）

编写新的 Quarto 文档时，请勿阅读这些参考资料。 只有在用户明确要求转换或迁移现有项目时，才阅读与源格式对应的参考资料。

• 将 R Markdown（.Rmd）转换为 Quarto：references/conversion-rmarkdown.md
• bookdown 项目：references/conversion-bookdown.md
• xaringan 幻灯片：references/conversion-xaringan.md
• distill 文章：references/conversion-distill.md
• blogdown 网站：references/conversion-blogdown.md
• 将 Jupyter notebook（.ipynb）转换为 Quarto 或从 Quarto 转换：references/conversion-jupyter.md

QMD 基础

基本文档结构

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

Content goes here.

Quarto 文档由两个主要部分组成：

1. YAML 前置元数据：位于顶部的元数据和配置，由 --- 括起来。
2. Markdown 内容：使用标准 Markdown 语法编写的正文。

Div 和 Span

Div 使用三个冒号的围栏语法：

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

Span 使用方括号语法：

This is [important text]{.highlight}.

详情：references/divs-and-spans.md

代码单元格选项语法

代码单元格以三个反引号和花括号中的语言标识符开头。 代码单元格是可以执行并生成输出的代码块。

Quarto 使用语言的注释符号加上 | 来设置单元格选项。选项使用连字符，而不是点号（例如，fig-cap，而非 fig.cap）。

• R、Python、Julia：#|
• Mermaid：%%|
• Graphviz/DOT：//|

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

# code that produces a figure
```

在 YAML 前置元数据中设置文档级默认值：

execute:
  echo: false
  warning: false

缓存 — 引擎差异至关重要： 仅对 R 代码单元格（knitr 引擎）建议使用 #| cache: true。 切勿对其他语言的单元格建议这样做——此选项不起作用，并且会被静默忽略。 使用 knitr 以外的引擎时，唯一正确的做法是在顶层 YAML 前置元数据中设置 execute: cache: true。 Python/Jupyter 需要 jupyter-cache（pip install jupyter-cache）：

execute:
  cache: true

详情：references/code-cells.md

交叉引用

标签必须以类型前缀开头。使用 @ 引用：

• 图：使用 fig- 前缀，例如，#| label: fig-plot → @fig-plot
• 表格：使用 tbl- 前缀，例如，#| label: tbl-data → @tbl-data
• 章节：使用 sec- 前缀，例如，{#sec-intro} → @sec-intro
• 公式：使用 eq- 前缀，例如，{#eq-model} → @eq-model

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

# code that produces a figure
```

See @fig-plot for the results.

详情：references/cross-references.md

提示块

五种类型：note、warning、important、tip、caution。

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

::: {.callout-warning}

## Custom Title

This is a warning with a custom title.

:::

详情：references/callouts.md

图

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

子图：

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

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

Main caption for the group.
:::

详情：references/figures.md

表格

::: {#tbl-example}

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

Table caption.
:::

详情：references/tables.md

引文

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

在 YAML 中配置：

bibliography: references.bib
csl: apa.csl

详情：references/citations.md

常见工作流

创建 HTML 文档

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

创建 PDF 文档

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

创建 RevealJS 演示文稿

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

## First Slide

Content here.

## Second Slide

More content.

设置 Quarto 项目

在项目根目录中创建 _quarto.yml：

project:
  type: website

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

format:
  html:
    theme: cosmo

资源

• Quarto 文档
• Quarto 指南
• Quarto 扩展
• 社区扩展列表