quarto-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quarto Authoring

Quarto 文档创作

This skill is based on Quarto CLI v1.8.26.

本技能基于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: Convert R Markdown to Quarto Use: references/conversion-rmarkdown.md

Task: Migrate bookdown project Use: references/conversion-bookdown.md

Task: Migrate xaringan slides Use: references/conversion-xaringan.md

Task: Migrate distill article Use: references/conversion-distill.md

Task: Migrate blogdown site Use: references/conversion-blogdown.md

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

任务：编写新的Quarto文档操作：遵循下方的「QMD核心要点」，然后查看具体参考文件

任务：将R Markdown转换为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

任务：添加交叉引用操作：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语法检查规则操作：references/markdown-linting.md

QMD Essentials

QMD核心要点

Basic Document Structure

基础文档结构

markdown

---
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.

markdown

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

Content goes here.

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

YAML头部元数据：位于文档顶部的元数据和配置信息，由
```
---
```
包裹。
Markdown内容主体：使用标准Markdown语法编写的文档主体。

Divs and Spans

Div和Span

Divs use fenced syntax with three colons:

markdown

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

Spans use bracketed syntax:

markdown

This is [important text]{.highlight}.

Details: references/divs-and-spans.md

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

markdown

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

Span使用括号语法：

markdown

This is [important text]{.highlight}.

详情：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:
```
//|
```

markdown

```{r}
#| 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:

yaml

execute:
  echo: false
  warning: false

Details: references/code-cells.md

代码单元格以三个反引号开头，大括号内包含语言标识符。代码单元格是可执行的代码块，运行后可生成输出。

Quarto使用语言的注释符号 +

来设置单元格选项。选项使用短横线，而非点（例如：

fig-cap

而非

fig.cap

）。

R、Python：
```
#|
```
Mermaid：
```
%%|
```
Graphviz/DOT：
```
//|
```

markdown

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

plot(x, y)
```

常用执行选项：

选项	描述	可选值
`eval`	执行代码	`true` , `false`
`echo`	显示代码	`true` , `false` , `fenced`
`output`	包含输出内容	`true` , `false` , `asis`
`warning`	显示警告信息	`true` , `false`
`error`	显示错误信息	`true` , `false`
`include`	在输出中包含单元格	`true` , `false`

可在YAML头部元数据中设置文档级默认选项：

yaml

execute:
  echo: false
  warning: false

详情：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
```

markdown

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

See @fig-plot for the results.

Details: references/cross-references.md

标签必须以类型前缀开头，使用

进行引用：

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

markdown

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

See @fig-plot for the results.

详情：references/cross-references.md

Callout Blocks

提示块

Five types:

note

warning

important

tip

caution

markdown

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

::: {.callout-warning}

五种类型：

note

（注释）、

warning

（警告）、

important

（重要提示）、

tip

（技巧）、

caution

（注意）。

markdown

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

::: {.callout-warning}

Custom Title

This is a warning with a custom title.

:::


Details: [references/callouts.md](references/callouts.md)

This is a warning with a custom title.

:::


详情：[references/callouts.md](references/callouts.md)

Figures

图表

markdown

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

Subfigures:

markdown

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

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

Main caption for the group.
:::

Details: references/figures.md

markdown

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

子图表：

markdown

::: {#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

Tables

表格

markdown

::: {#tbl-example}

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

Table caption.
:::

Details: references/tables.md

markdown

::: {#tbl-example}

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

Table caption.
:::

详情：references/tables.md

Citations

引用

markdown

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

Configure in YAML:

yaml

bibliography: references.bib
csl: apa.csl

Details: references/citations.md

markdown

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

在YAML中配置：

yaml

bibliography: references.bib
csl: apa.csl

详情：references/citations.md

Common Workflows

常见工作流

Creating an HTML Document

创建HTML文档

yaml

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

yaml

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

Creating a PDF Document

创建PDF文档

yaml

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

yaml

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

Creating a RevealJS Presentation

创建RevealJS演示文稿

markdown

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

markdown

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

First Slide

Content here.

Second Slide

Setting Up a Quarto Project

设置Quarto项目

Create

_quarto.yml

in the project root:

yaml

project:
  type: website

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

format:
  html:
    theme: cosmo

在项目根目录创建

_quarto.yml

文件：

yaml

project:
  type: website

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

format:
  html:
    theme: cosmo

quarto-authoring

Original

Translation

Quarto Authoring

Quarto 文档创作

When to Use What

场景对应操作

QMD Essentials

QMD核心要点

Basic Document Structure

基础文档结构

Divs and Spans

Div和Span

Code Cell Options Syntax

代码单元格选项语法

Cross-References

交叉引用

Callout Blocks

提示块

Custom Title

Custom Title

Figures

图表

Tables

表格

Citations

引用

Common Workflows

常见工作流

Creating an HTML Document

创建HTML文档

Creating a PDF Document

创建PDF文档

Creating a RevealJS Presentation

创建RevealJS演示文稿

First Slide

First Slide

Second Slide

Second Slide

Setting Up a Quarto Project

设置Quarto项目

Resources

资源