教程：创作

选择你的工具

VS Code
Jupyter
RStudio
Neovim
编辑器

概述

在本教程中，我们将探索更多 Quarto 的创作功能。我们将介绍如何将文档渲染为多种格式，并向您展示如何添加目录、方程、引用、交叉引用等组件。

输出格式

Quarto 支持将笔记本渲染为数十种不同的输出格式。默认情况下，使用 html 格式，但您可以在文档选项中指定替代格式（或多种格式）。

格式选项

让我们创建一个新文件 (authoring.qmd)，并定义多种格式以供渲染，为每种格式添加一些选项。提醒一下，文档选项在源文件开头的 YAML 中指定。

---
title: "Quarto Document"
author: "Norah Jones"
format: pdf
---

我们指定 pdf 作为默认输出格式（如果我们省略 format 选项，则默认为 html）。

让我们添加一些选项来控制我们的 PDF 输出。

---
title: "Quarto Document"
author: "Norah Jones"
format: 
  pdf: 
    toc: true
    number-sections: true
---

多种格式

您创建的某些文档可能只有单一输出格式，但在许多情况下，支持多种格式将是可取的。让我们为我们的文档添加 html 和 docx 格式。

---
title: "Quarto Document"
author: "Norah Jones"
toc: true
number-sections: true
highlight-style: pygments
format: 
  html: 
    code-fold: true
    html-math-method: katex
  pdf: 
    geometry: 
      - top=30mm
      - left=20mm
  docx: default
---

这里有很多内容！让我们分解一下。前两行是与输出格式无关的通用文档元数据。

title: "Quarto Document"
author: "Norah Jones"

接下来的三行是适用于所有格式的文档格式选项，这就是为什么它们在根级别指定。

toc: true
number-sections: true
highlight-style: pygments

接下来，我们有 format 选项，我们在这里提供特定于格式的选项。

format:
  html: 
    code-fold: true
    html-math-method: katex
  pdf:
    geometry: 
      - top=30mm
      - left=20mm
  docx: default

html 和 pdf 格式各自提供了一两个选项。例如，对于 HTML 输出，我们希望用户能够控制是否显示或隐藏代码（code-fold: true），并使用 katex 处理数学文本。对于 PDF，我们定义了一些页边距。docx 格式略有不同——它指定了 docx: default。这意味着仅使用该格式的所有默认选项。

渲染

在文档选项中指定的格式定义了默认渲染的内容。如果我们使用以下命令渲染包含上述所有选项的文档。

Terminal

quarto render authoring.qmd

那么将创建以下文件。

authoring.html
authoring.pdf
authoring.docx

我们可以使用 --to 选项选择一种或多种格式。

Terminal

quarto render authoring.qmd --to docx
quarto render authoring.qmd --to docx,pdf

请注意，目标文件（在本例中为 authoring.qmd）应始终是命令行参数中的第一个。

如果需要，我们还可以渲染未在文档选项中指定的格式。

Terminal

quarto render authoring.qmd --to odt

由于 odt 格式未包含在文档选项中，因此将使用该格式的默认选项。

章节

您可以使用目录和/或章节编号，使读者更容易浏览您的文档。通过在文档选项中添加 toc 和/或 number-sections 选项来实现这一点。请注意，这些选项通常在根级别指定，因为它们适用于所有格式。

---
title: Quarto Basics
author: Norah Jones
date: 'May 22, 2021'
toc: true
number-sections: true
---

## Colors

- Red
- Green 
- Blue

## Shapes

- Square
- Circle
- Triangle

## Textures

- Smooth
- Bumpy
- Fuzzy

以下是渲染为 HTML 时的文档外观。

有许多选项可用于控制目录和章节编号的行为。有关更多详细信息，请参阅输出格式文档（例如 HTML、PDF、MS Word）。

方程

您可以在 Markdown 中使用 LaTeX 方程。

Einstein's theory of special relatively that expresses the equivalence of mass and energy:

$E = mc^{2}$

渲染后如下所示。

Einstein’s theory of special relatively that expresses the equivalence of mass and energy:

$E = mc^{2}$

行内公式用 $…$ 分隔。要在新行中创建公式（显示公式），请使用 $$…$$。有关更多详细信息，请参阅markdown 公式的文档。

引用

要在 Quarto 文档中引用其他作品，首先创建一个支持格式的参考文献文件（BibTeX 或 CSL）。然后，使用 bibliography YAML 元数据选项将参考文献链接到您的文档。

以下是一个包含参考文献和单个引用的文档示例。

---
title: Quarto Basics
format: html
bibliography: references.bib
jupyter: python3
---

## 概述

Knuth 说总是要善于表达 [@knuth1984]。

```{python}
1 + 1
```

## 参考文献

请注意，参考文献中的条目使用 @citeid 语法进行引用。

 Knuth 说总是要善于表达 [@knuth1984]。

参考文献将包含在文档末尾，因此我们在源文件底部包含一个 ## 参考文献 标题。

以下是渲染后的文档外观。

渲染后的文档，底部有参考文献部分，内容为 'Knuth, Donald E. 1984. Literate Programming. The Computer Journal 27 (2): 97-111.'

@ 引用语法非常灵活，支持前缀、后缀、定位符和内文引用。要了解更多信息，请参阅引用的文档。

交叉引用

交叉引用通过提供编号引用和超链接到图表、表格、公式和章节，使读者更容易导航您的文档。通常，可交叉引用的实体需要一个标签（唯一标识符）和一个标题。

此示例说明了如何交叉引用各种类型的实体。

---
title: Quarto Crossrefs
format: html
jupyter: python3
---

## 概述

请参见 @fig-simple 在 @sec-plot 中查看简单图表示例。

请参见 @eq-stddev 以更好地理解标准差。

## 图表 {#sec-plot}

```{python}
#| label: fig-simple
#| fig-cap: "简单图表"
import matplotlib.pyplot as plt
plt.plot([1,23,2,4])
plt.show()
```

## 公式 {#sec-equation}

$$
s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}
$$ {#eq-stddev}

我们交叉引用了章节、图表和公式。下表显示了我们如何表达这些内容。

实体	引用	标签 / 标题
章节	`@sec-plot`	添加到标题的 ID： `# 图表 {#sec-plot}`
图表	`@fig-simple`	代码单元格中的 YAML 选项： `#\| label: fig-simple #\| fig-cap: "简单图表"`
公式	`@eq-stddev`	显示公式末尾： `$$ {#eq-stddev}`

最后，以下是渲染后的文档外观。

渲染后的页面，带有链接到图表和公式的交叉引用。

要了解更多信息，包括如何自定义标题和引用文本（例如使用“图”而不是“图表”），请参阅交叉引用的文章。

标注

标注是吸引额外注意某些概念或更清晰地表明某些内容是补充性的或仅适用于某些场景的绝佳方式。

标注是具有特殊标注属性的 markdown div。要在 markdown 单元格中创建标注，请在文档中输入以下内容。

::: {.callout-note}
请注意，有五种类型的标注，包括：
`note`, `tip`, `warning`, `caution`, 和 `important`。
:::

渲染后如下所示。

Note

请注意，有五种类型的标注，包括 note, tip, warning, caution, 和 important。

你可以在Callouts文档中了解更多关于不同类型的标注及其外观选项的信息。

文章布局

Quarto文章的正文默认宽度约为700像素。这个宽度是根据优化可读性选择的。这通常会在文档的页边距中留下一些可用空间，有几种方法可以利用这些空间。

在这个例子中，我们使用reference-location选项来指示我们希望脚注放置在右页边距中。

我们还使用column: screen-inset单元格选项来指示我们希望我们的图表占据屏幕的全宽，并带有一个小的内边距。

---
title: Quarto布局
format: html
reference-location: margin
jupyter: python3
---

## 放置颜色条

颜色条指示图像数据的定量范围。
在图表中放置颜色条并不简单，因为需要为它们腾出空间。最简单的情况是为每个轴添加一个颜色条：^[参见[Matplotlib图库](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/colorbar_placement.html)以进一步探索颜色条]。

```{python}
#| code-fold: true
#| column: screen-inset
import matplotlib.pyplot as plt
import numpy as np

fig, axs = plt.subplots(2, 2)
fig.set_size_inches(20, 8)
cmaps = ['RdBu_r', 'viridis']
for col in range(2):
    for row in range(2):
        ax = axs[row, col]
        pcm = ax.pcolormesh(
          np.random.random((20, 20)) * (col + 1),
          cmap=cmaps[col]
        )
        fig.colorbar(pcm, ax=ax)
plt.show()
```

以下是渲染后的文档外观。

文档顶部有Quarto布局标题，接着是放置颜色条标题，下方有文字。文字旁边是页边距中的脚注。文字下方是一个可切换的代码小部件，用于隐藏/显示代码，接着是两行两列显示的四个图表。

你可以在页边距中放置引用、脚注和侧边栏。你还可以为图表、表格或其他内容定义自定义列跨度。有关更多详细信息，请参阅文章布局的文档。

进一步学习

你现在已掌握了使用 Quarto 的基础知识！一旦你感到在创建和自定义文档方面得心应手，以下是一些值得探索的进阶内容：

演示文稿 — 使用与创建文档相同的语法，制作 PowerPoint、Beamer 和 Revealjs 演示文稿。
网站 — 将文档集合发布为网站。网站支持多种导航形式和全文搜索功能。
博客 — 创建一个包含关于页面、灵活的文章列表、分类、RSS 订阅以及超过二十种主题的博客。
书籍 — 以印刷（PDF、MS Word）和在线（HTML、ePub）格式创作书籍和手稿。
交互性 — 加入互动组件，帮助读者更深入地探索你所呈现的概念和数据。

请参阅关于在 Quarto 中使用 Neovim的文章，以了解更多关于安装、使用和自定义 Neovim 进行 Quarto 创作的信息。