教程：你好，Quarto
VS Code
Jupyter
RStudio
Neovim
编辑器
概览
在本教程中，我们将向你展示如何将你喜欢的文本编辑器与Quarto结合使用。 你将编辑纯文本的.qmd文件，并在工作时在网络浏览器中预览渲染的文档。
下面是对这个过程的概览。
左侧的笔记本被渲染成你在右侧看到的HTML版本。 这是Quarto发布的基本模型——将一个源文档（在这个例子中是一个笔记本）渲染成多种输出格式，包括HTML、PDF、MS Word等。
本教程将使用matplotlib和plotly Python包——你可以使用下表中的命令来安装它们。
| 平台 | 命令 |
|---|---|
| Mac/Linux | {.bash filename="终端"} | python3 -m pip install jupyter matplotlib plotly |
| Windows | 终端 |
编辑器模式
如果你使用的是VS Code，在继续之前应安装Quarto扩展。 该扩展提供了markdown和嵌入语言的语法高亮显示，嵌入语言的补全（例如Python、R、Julia、LaTeX等），运行单元格和选定行（或多行）的命令和快捷键，以及更多功能。
还有其他几种编辑器的Quarto语法高亮模式可供选择：
| 编辑器 | 扩展 |
|---|---|
| Emacs | https://github.com/quarto-dev/quarto-emacs |
| Vim / Neovim | https://github.com/quarto-dev/quarto-vim |
| Neovim | https://github.com/quarto-dev/quarto-nvim |
| Sublime Text | https://github.com/quarto-dev/quarto-sublime |
渲染
我们将从一个简单的例子（hello.qmd）开始，将其渲染为几种格式。 如果你想在自己的环境中一步一步地跟随，创建一个名为hello.qmd的新文件，并将以下内容复制到其中。
---
title: "Quarto基础"
format:
html:
code-fold: true
jupyter: python3
---
要查看极坐标轴上的线图示例，请参见@fig-polar。
```{python}
#| label: fig-polar
#| fig-cap: "极坐标轴上的线图"
import numpy as np
import matplotlib.pyplot as plt
r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
subplot_kw = {'projection': 'polar'}
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```接下来，打开一个终端并切换到包含hello.qmd的目录。
让我们先渲染文档为几种格式。
终端
quarto render hello.qmd --to html
quarto render hello.qmd --to docx请注意，目标文件（在这个例子中是hello.qmd）应始终是命令行的第一个参数。
当你使用Quarto渲染一个.qmd文件时，可执行代码块由Jupyter处理，结果的代码、markdown和输出组合被转换为纯markdown。 然后，这个markdown由Pandoc处理，创建最终的格式。
创作
quarto render命令用于创建你的文档的最终版本以供分发。 然而，在创作过程中，你将使用quarto preview命令。 现在从终端尝试使用hello.qmd。
终端
quarto preview hello.qmd这将渲染你的文档并在网络浏览器中显示它。 
你可能希望将编辑器和浏览器预览并排放置，以便在工作中看到变化。
要查看实时预览的实际效果：
将定义
theta的代码行更改为以下内容：theta = 4 * np.pi * r保存文件。 文档会重新渲染，浏览器预览也会更新。
这是使用 Quarto 进行创作的基本工作流程。
在 hello.qmd 中有几种不同类型的内容，让我们逐一处理。
YAML 选项
文件顶部有一个包含文档级选项的 YAML 块。
---
title: "Quarto 基础"
format:
html:
code-fold: true
jupyter: python3
---尝试将 code-fold 选项更改为 false：
format:
html:
code-fold: false然后保存文件。 你会注意到代码现在显示在图表上方，而之前它被隐藏在一个可以用来显示代码的 代码 按钮后面。
Markdown
叙述性内容使用 markdown 编写。 这里我们指定了一个标题，并交叉引用了下面代码单元格中创建的图表。
## 极坐标轴
要演示极坐标轴上的线图，请参见 @fig-polar。尝试更改标题并保存笔记本——预览会用新的标题文本更新。
代码单元格
代码单元格包含在渲染过程中要运行的可执行代码，输出（以及可选的代码）包含在渲染文档中。
```{python}
#| label: fig-polar
#| fig-cap: "极坐标轴上的线图"
import numpy as np
import matplotlib.pyplot as plt
r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
subplot_kw = {'projection': 'polar'}
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```你可能对这里给出的 Matplotlib 代码很熟悉。 然而，代码单元格顶部有一些不太熟悉的组件：label 和 fig-cap 选项。 单元格选项使用特殊前缀的注释（#|）以 YAML 格式编写。
在这个例子中，单元格选项用于使图表可交叉引用。 尝试更改 fig-cap 和/或代码，运行单元格，然后保存文件以查看更新的预览。
你可以应用各种各样的 单元格选项 来定制你的输出。 我们将在下一篇教程中深入探讨这些选项。
对于图表特别有用的单元格选项之一是 fig-alt，它使你能够为图像添加替代文本，以方便视觉障碍用户。 了解更多信息，请参阅 Amy Cesal 关于 为数据可视化编写替代文本 的文章。
下一步
你现在已了解创建和编写Quarto文档的基础知识。以下教程将更深入地探讨Quarto：