您好,Quarto

概述

在本教程中，我们将向您展示如何将 Quarto 与 VS Code 结合使用。在开始之前，您应该安装Quarto VS Code Extension，其中包括许多可增强 Quarto 工作的工具，包括：

• quarto文档的集成渲染和预览。
• Markdown 和嵌入式语言的语法突出显示
• YAML 选项的完成和诊断
• 嵌入式语言的补全（例如Python、R、Julia等）
• 用于运行单元格和选定行的命令和键绑定。
• 您可以从VS Code 的Extensions tab、Extension Marketplace、Open VSX Registry 或直接从VISX extension file安装 Quarto 扩展。

注解

本教程重点介绍在 VS Code 中编辑纯文本 Quarto ’.qmd’文件。根据您的偏好和手头的任务，还有两种可用于Quarto文档的其他编辑模式：Visual Editor和Notebook Editor。出于学习目的，我们建议您使用 VS Code 文本编辑器完成本教程，然后在掌握基础知识后探索使用其他编辑模式。

基本工作流程

Quarto .qmd 包含 Markdown 和可执行代码单元的组合。 在 VS Code 中编辑和预览文件可能如下所示.qmd:

左侧的文档将 rendered 渲染为您在右侧看到的 HTML 版本。 这是Quarto部署的基本模型——获取源文档并将其呈现为各种输出格式，包括 HTML、PDF、MS Word 等。

本教程将使用matplotlib和plotlyPython包 ，下表给出了可用于安装它们的命令：

Platform	Commands
Mac/Linux	Terminal python3 -m pip install jupyter matplotlib plotly
Windows	Terminal py -m pip install jupyter matplotlib plotly

注解

请注意，虽然本教程使用 Python，但也很好地支持使用 Julia（通过IJulia kernel）。有关更多详细信息，请参阅有关使用 Julia的文章。

渲染和预览

我们首先将一个简单的示例 ( hello.qmd) 渲染为几种格式。 如果您想在自己的环境中逐步执行操作，请创建一个名为 的新文件hello.qmd并将以下内容复制到其中。

---
title: "Quarto Basics"
format:
  html:
    code-fold: true
jupyter: python3
---

For a demonstration of a line plot on a polar axis, see @fig-polar.

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

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()
```

请注意，如果您按照步骤操作，请务必安装所需的依赖项（如果尚未安装）：

Platform	Commands
Mac/Linux	Terminal python3 -m pip install jupyter matplotlib plotly
Windows	Terminal py -m pip install jupyter matplotlib plotly

T要渲染和预览，请执行 Quarto: Preview 命令. 您也可以使用Ctrl+Shift+K键盘快捷键或编辑器右上角的 Preview 按钮：

请注意，在 Mac 上，您应该使用 Cmd 而不是 Ctrl 作为所有Quarto快捷键的前缀。

如何运行

当您使用 .qmd Quarto 渲染文件时，可执行代码块由 Jupyter 处理，并且代码、Markdown 和输出的结果组合将转换为纯 Markdown。然后，这个 Markdown 由Pandoc处理，创建最终的格式。

创作

让我们尝试做一些小的改变，然后重新渲染：

1. 更改定义的代码行theta如下：

   theta = 4 * np.pi * r

2. 重新渲染文件（使用Quarto: Preview：或Ctrl+Shift+K快捷方式） 渲染文档，并更新浏览器预览。

这是使用 Quarto 进行创作的基本工作流程。

您不需要在渲染之前保存文件（因为渲染时会自动发生）。如果您愿意，可以将 Quarto 扩展配置为在保存文档时进行渲染。有关其他详细信息，请参阅有关Render on Save的文档。

运行代码块

您无需完全渲染文档即可迭代代码单元。您会注意到代码单元格上方有一个 Run Cell 按钮。单击该按钮执行该单元（输出在 Jupyter 交互式控制台中并排显示）：

使用 执行当前单元格 Ctrl+Shift+Enter,使用 执行当前行 Ctrl+Enter，或使用上一个单元格执行 Ctrl+Alt+P （请注意，在 Mac 上，您应该使用Cmd 而不是 Ctrl 作为所有 Quarto 键盘快捷键的前缀）。

有几种不同类型的内容 hello.qmd，让我们对每种类型进行一些研究。

YAML 选择

文件顶部有一个包含文档级别选项的 YAML 块。

---
title: "Quarto Basics"
format:
  html:
    code-fold: true
jupyter: python3
---

尝试将code-fold选项更改为false：

format: 
  html:
    code-fold: false

然后重新渲染文档（同样，渲染前无需保存）。您会注意到代码现在显示在绘图上方，而之前它是通过可用于显示它的 Code 按钮隐藏的。

Markdown 单元块

叙述内容是使用 Markdown 编写的。 在这里，我们指定标题和对下面代码单元中创建的图形的交叉引用。

## 极坐标

For a demonstration of a line plot on a polar axis, see @fig-polar.

尝试更改标题并重新渲染 - 预览将使用新的标题文本进行更新。

代码块

代码块包含要在渲染期间运行的可执行代码，输出（以及可选的代码）包含在渲染的文档中。

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

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 和/或 代码，然后重新渲染以查看更新后的预览。 您可以应用多种 cell options 来定制输出。 我们将在下一个教程中深入研究这些选项。

注解

对于图形来说，一个特别有用的单元格选项是 fig-alt，它使您能够为有视觉障碍的用户向图像添加替代文本。请参阅 Amy Cesal 的有关为Writing Alt Text for Data Visualization 的文章以了解更多信息。

外部预览

在本教程中，我们演示了在 VS Code 的窗格中预览渲染的输出。如果您更喜欢使用外部浏览器进行预览（或者根本没有通过渲染触发预览），您可以使用 Preview Type 选项来指定替代行为：

下一步

您现在已经了解了创建和创作Quarto文档的基础知识。以下教程更深入地探讨了Quarto：

• 教程: 计算方法 — 了解如何定制可执行代码块的行为和输出。

• 教程: 写作 — 了解有关输出格式和技术写作功能（如引文、交叉引用和高级布局）的更多信息。

此外，您可能希望了解 VS Code 中可用的 Quarto文档的其他编辑模式：

• 用于WYSIWYG(所见即所得)Visual Editor 编辑 .qmd 文档 .

• 用Notebook Editor 编辑 .ipynb notebooks 文档。