教程：创作

概述

在本教程中，我们将向您展示如何在 Jupyter Lab 中创作 Quarto 文档。 特别地，我们将讨论您可以生成的各种文档格式，并展示如何添加目录、方程、引用、交叉引用等组件。

输出格式

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

格式选项

让我们创建一个笔记本，并定义将其渲染到的各种格式，并为每种格式添加一些选项。 提醒一下，文档选项在笔记本开头的“Raw”单元格中的 YAML 中指定。 要创建一个 Raw 单元格，请在笔记本顶部添加一个单元格，并使用笔记本工具栏将其类型设置为 Raw：

现在，让我们添加一些基本的文档元数据和默认输出格式。

---
title: "Quarto 文档"
author: "诺拉·琼斯"
format: pdf
jupyter: python3
---

我们指定了 pdf 作为默认输出格式（如果我们排除 format 选项，那么它将默认为 html）。

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

---
title: "Quarto 文档"
author: "诺拉·琼斯"
format: 
  pdf: 
    toc: true
    number-sections: true
jupyter: python3
---

多格式

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

---
title: "Quarto 文档"
author: "诺拉·琼斯"
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
jupyter: python3
---

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

title: "Quarto 文档"
author: "诺拉·琼斯"

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

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

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

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

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

渲染

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

Terminal

quarto render notebook.ipynb

那么，将创建以下文件。

• notebook.html
• notebook.pdf
• notebook.docx

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

Terminal

quarto render notebook.ipynb --to docx
quarto render notebook.ipynb --to docx,pdf

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

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

Terminal

quarto render notebook.ipynb --to odt

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

请注意，当渲染 .ipynb 时，Quarto 不会 默认执行笔记本中的单元格（假设您在编辑笔记本时已经执行了它们）。如果您想执行这些单元格，可以传递 --execute 标志来渲染。

Terminal

quarto render notebook.ipynb --execute

章节

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

---
title: Quarto基础
author: 诺拉·琼斯
date: '2021年5月22日'
toc: true
number-sections: true
jupyter: python3
---

## 颜色

- 红色
- 绿色
- 蓝色

## 形状

- 正方形
- 圆形
- 三角形

## 纹理

- 光滑
- 凹凸不平
- 毛茸茸

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

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

公式

你可以在Jupyter Lab中的markdown单元格内添加LaTeX公式。

爱因斯坦的狭义相对论理论，表达了质量和能量之间的等价关系：

$E = mc^{2}$

\(E = mc^{2}\)

当你运行单元格时，公式会被渲染。

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

引用

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

以下是一个包含参考文献和单个引用的笔记本。请注意，markdown单元格未执行，因此你可以看到所有的语法。

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

## 概述

Knuth说，总是要有文学性[@knuth1984]。

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

## 参考文献

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

 Knuth说，总是要有文学性[@knuth1984]。

参考文献将包含在文档的末尾，因此我们在笔记本底部添加了一个 ## 参考文献 标题。

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

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

交叉引用

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

下面的笔记本演示了如何交叉引用各种类型的实体。同样，markdown单元格再次未执行，以便语法可见。

---
title: Quarto交叉引用
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}

\[ x + 1 \]

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

实体	引用	标签 / 标题
章节	@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`.
:::

当我们最终使用Quarto渲染文档时，提示框会按预期显示。

Note

注意，有五种类型的提示框，包括 note, tip, warning, caution, 和 important.

您可以在提示框文档中了解更多关于不同类型提示框及其外观选项的信息。

文章布局

Quarto文章的主体默认宽度约为700像素。 此宽度选择是为了优化可读性。 这通常会在文档的边距中留下一些可用空间，您可以通过几种方式利用这些空间。

在这个笔记本中，我们使用reference-location选项来指示我们希望将脚注放在右边距中。

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

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

## 放置颜色条

颜色条指示图像数据的定量范围。
在图表中放置颜色条并非易事，因为需要为它们腾出空间。
最简单的情况是为每个轴附加一个颜色条：^[参见[Matplotlib Gallery](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 的基础知识！一旦你感到在创建和自定义文档方面得心应手，以下是一些值得探索的进阶内容：

• 演示文稿 — 使用与创建文档相同的语法，制作 PowerPoint、Beamer 和 Revealjs 演示文稿。

• 网站 — 将文档集合发布为网站。网站支持多种导航形式和全文搜索功能。

• 博客 — 创建一个包含关于页面、灵活的文章列表、分类、RSS 订阅以及超过二十种主题的博客。

• 书籍 — 以印刷（PDF、MS Word）和在线（HTML、ePub）格式创作书籍和手稿。

• 交互性 — 加入互动组件，帮助读者更深入地探索你所呈现的概念和数据。