VS

概述

在本教程中，我们将介绍如何将 Quarto 与 VS Code 配合使用。在开始之前，应安装 Quarto VS Code 扩展，其中包括许多增强 Quarto 使用的工具，包括：
  • 集成了 Quarto 文档的渲染和预览功能。
  • Markdown 和嵌入式语言的语法高亮显示
  • YAML 选项的完成和诊断
  • 完成嵌入式语言（例如 Python、R、Julia 等）
  • 用于运行单元格和选定行的命令和键绑定。
可以从 VS Code 的“扩展”选项卡、扩展市场、Open VSX 注册表或直接从 VISX 扩展文件安装 Quarto 扩展。

注意

本教程重点介绍如何在 VS Code 中编辑纯文本 Quarto 文件。根据您的偏好和手头的任务，Quarto 文档还有另外两种编辑模式：可视化编辑器和笔记本编辑器。出于学习目的，我们建议你使用 VS Code 文本编辑器完成本教程，然后在掌握基础知识后探索使用其他编辑模式。<font style="background-color:rgb(248, 249, 250);">.qmd</font> ### 基本工作流程 Quarto 文件包含 markdown 和可执行代码单元格的组合。下面是 VS Code 中编辑和预览文件的外观：Here’s what it might look like in VS Code to edit and preview a file：<font style="background-color:rgb(248, 249, 250);">.qmd</font>``<font style="background-color:rgb(248, 249, 250);">.qmd</font> 使用流程 - 图1 左边的文档将呈现为您在右边看到的 HTML 版本。这是 Quarto 出版的基本模型 - 获取源文档并将其呈现为各种输出格式，包括 HTML、PDF、MS Word 等。 这些教程将使用 和 Python 包，下表给出了可用于安装它们的命令。<font style="background-color:rgb(248, 249, 250);">matplotlib</font>``<font style="background-color:rgb(248, 249, 250);">plotly</font> | 平台 | 命令 | | —- | —- | | Mac/Linux操作系统 | Terminal
python3 -m pip install jupyter matplotlib plotly | | Windows | Terminal
py -m pip install jupyter matplotlib plotly | Note Note that while this tutorial uses Python, using Julia (via the IJulia kernel) is also well supported. See the article on Using Julia for additional details.

Render and Preview

We’ll start out by rendering a simple example () to a couple of formats. If you want to follow along step-by-step in your own environment, create a new file named and copy the following content into it.<font style="background-color:rgb(248, 249, 250);">hello.qmd</font>``<font style="background-color:rgb(248, 249, 250);">hello.qmd</font> plain --- 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() 请注意，如果您正在遵循以下操作，请务必安装所需的依赖项（如果尚未安装）：
平台 命令
Mac/Linux操作系统 Terminal
python3 -m pip install jupyter matplotlib plotly
窗户 Terminal
py -m pip install jupyter matplotlib plotly
要渲染和预览，请执行 Quarto： Preview 命令。您也可以使用键盘快捷键或编辑器右上角的“预览”按钮 （使用流程 - 图2）：Ctrl+Shift+K

使用流程 - 图3

请注意，在 Mac 上，您应该使用而不是作为所有 Quarto 键盘快捷键的前缀。<font style="background-color:rgb(248, 249, 250);">Cmd</font>``<font style="background-color:rgb(248, 249, 250);">Ctrl</font> ### 它是如何工作的 使用 Quarto 渲染文件时，Jupyter 会处理可执行代码块，并将生成的代码、Markdown 和输出组合转换为普通 Markdown。然后，Pandoc 会处理此 Markdown，从而创建完成的格式。<font style="background-color:rgb(248, 249, 250);">.qmd</font> 使用流程 - 图4 ### 创作 让我们试着做一个小的改变，然后重新渲染：
  1. 更改定义如下的代码行：<font style="background-color:rgb(248, 249, 250);">theta</font>
theta = 4 np.pi r
  1. 重新渲染文件（使用 Quarto： Preview 或快捷方式） 文档已呈现，浏览器预览已更新。Ctrl+Shift+K
这是使用 Quarto 进行创作的基本工作流程。 在渲染之前不需要保存文件（因为这会在渲染时自动发生）。如果您愿意，可以将 Quarto 扩展配置为在保存文档时呈现。有关更多详细信息，请参阅有关“保存时渲染”的文档。

运行单元格

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

使用流程 - 图5

执行当前单元格 、当前行 和 或以前的单元格 （请注意，在 Mac 上，您应该使用而不是作为所有 Quarto 键盘快捷键的前缀）。Ctrl+Shift+EnterCtrl+EnterCtrl+Alt+P<font style="background-color:rgb(248, 249, 250);">Cmd</font>``<font style="background-color:rgb(248, 249, 250);">Ctrl</font> 中的内容有几种不同类型的，让我们对每种类型进行一些工作。<font style="background-color:rgb(248, 249, 250);">hello.qmd</font> ## YAML 选项 在文件的顶部有一个带有文档级别选项的 YAML 块。 
  1. ---
  2. title: "Quarto Basics"
  3. format:
  4.   html:
  5.     code-fold: true
  6. jupyter: python3
  7. ---
尝试将选项更改为：<font style="background-color:rgb(248, 249, 250);">code-fold</font>``<font style="background-color:rgb(248, 249, 250);">false</font> plain format: html: code-fold: false 然后重新渲染文档（同样，渲染前无需保存）。您会注意到，代码现在显示在绘图上方，而以前它使用可用于显示它的代码按钮隐藏。

降价

叙述性内容是使用 Markdown 编写的。在这里，我们指定一个标题和对在下面代码单元中创建的图形的交叉引用。 
  1. ## Polar Axis
  3. For a demonstration of a line plot on a polar axis, see @fig-polar.
尝试更改页眉并重新呈现 - 预览将使用新的页眉文本进行更新。

代码单元

代码单元包含要在渲染期间运行的可执行代码，输出（以及可选的代码）包含在渲染的文档中。 
  1. ```{python}
  2. #| label: fig-polar
  3. #| fig-cap: "A line plot on a polar axis"
  5. import numpy as np
  6. import matplotlib.pyplot as plt
  8. r = np.arange(0, 2, 0.01)
  9. theta = 2 * np.pi * r
  10. fig, ax = plt.subplots(
  11.   subplot_kw = {'projection': 'polar'} 
  12. )
  13. ax.plot(theta, r)
  14. ax.set_rticks([0.5, 1, 1.5, 2])
  15. ax.grid(True)
  16. plt.show()
  2. <font style="color:rgb(52, 58, 64);">您可能熟悉此处给出的 Matplotlib 代码。但是，代码单元格的顶部有一些不太熟悉的组件：和选项。单元格选项在 YAML 中使用特殊前缀的注释 （） 编写。</font>`<font style="background-color:rgb(248, 249, 250);">label</font>``<font style="background-color:rgb(248, 249, 250);">fig-cap</font>``<font style="background-color:rgb(248, 249, 250);">#|</font>`
  4. <font style="color:rgb(52, 58, 64);">在此示例中，单元格选项用于使图形可交叉引用。尝试更改和/或代码，然后重新呈现以查看更新的预览。</font>`<font style="background-color:rgb(248, 249, 250);">fig-cap</font>`
  6. <font style="color:rgb(52, 58, 64);">您可以应用多种</font>[<font style="color:rgb(52, 58, 64);">单元格选项</font>](https://quarto.org/docs/reference/cells/cells-jupyter.html)<font style="color:rgb(52, 58, 64);">来定制输出。我们将在下一个教程中深入探讨这些选项。</font>
  8. **<font style="color:rgb(52, 58, 64);background-color:rgb(233, 242, 252);">注意</font>**
  10. <font style="color:rgb(52, 58, 64);">对于图形来说，一个特别有用的单元格选项是 ，它使您能够为有视力障碍的用户向图像添加替代文本。请参阅 Amy Cesal 关于</font>[<font style="color:rgb(52, 58, 64);">为数据可视化编写替代文本</font>](https://medium.com/nightingale/writing-alt-text-for-data-visualization-2a218ef43f81)<font style="color:rgb(52, 58, 64);">的文章以了解更多信息。</font>`<font style="background-color:rgb(248, 249, 250);">fig-alt</font>`
  12. ## 外部预览
  13. <font style="color:rgb(52, 58, 64);">在本教程中，我们演示了如何在 VS Code 的窗格中预览呈现的输出。如果希望使用外部浏览器进行预览（或者完全不通过渲染触发预览），则可以使用</font>**<font style="color:rgb(52, 58, 64);">“预览类型</font>**<font style="color:rgb(52, 58, 64);">”选项指定替代行为：</font>
  15. ![](https://cdn.nlark.com/yuque/0/2024/png/39191047/1721718734757-e6524ad0-8215-42dc-bcb1-954bae58b90e.png)
  17. ## 下一步
  18. <font style="color:rgb(52, 58, 64);">您现在了解了创建和创作 Quarto 文档的基础知识。以下教程更深入地探讨了 Quarto：</font>
  20. + [<font style="color:rgb(52, 58, 64);">教程：计算</font>](https://quarto.org/docs/get-started/computations/)<font style="color:rgb(52, 58, 64);"> </font><font style="color:rgb(52, 58, 64);">— 了解如何定制可执行代码块的行为和输出。</font>
  21. + [<font style="color:rgb(52, 58, 64);">教程：创作</font>](https://quarto.org/docs/get-started/authoring/)<font style="color:rgb(52, 58, 64);"> </font><font style="color:rgb(52, 58, 64);">— 详细了解输出格式和技术写作功能，如引文、交叉引用和高级布局。</font>
  23. <font style="color:rgb(52, 58, 64);">此外，你可能希望了解 VS Code 中可用的 Quarto 文档的其他编辑模式：</font>
  25. + <font style="color:rgb(52, 58, 64);">用于所见即所得文档编辑</font>[<font style="color:rgb(52, 58, 64);">的可视化编辑</font>](https://quarto.org/docs/visual-editor/vscode/)<font style="color:rgb(52, 58, 64);">器。</font>`<font style="background-color:rgb(248, 249, 250);">.qmd</font>`
  26. + <font style="color:rgb(52, 58, 64);">用于编辑笔记本</font>[<font style="color:rgb(52, 58, 64);">的笔记本编辑器</font>](https://quarto.org/docs/tools/vscode-notebook.html)<font style="color:rgb(52, 58, 64);">。</font>`<font style="background-color:rgb(248, 249, 250);">.ipynb</font>`
  28. # j——教程：Hello， Quarto
  29. + [<font style="color:rgb(52, 58, 64);">VS 代码</font>](https://quarto.org/docs/get-started/hello/vscode.html)
  30. + [<font style="color:rgb(52, 58, 64);">Jupyter</font>](https://quarto.org/docs/get-started/hello/jupyter.html)
  31. + [<font style="color:rgb(52, 58, 64);">RStudio</font>](https://quarto.org/docs/get-started/hello/rstudio.html)
  32. + [<font style="color:rgb(52, 58, 64);">Neovim的</font>](https://quarto.org/docs/get-started/hello/neovim.html)
  33. + [<font style="color:rgb(52, 58, 64);">编辑 器</font>](https://quarto.org/docs/get-started/hello/text-editor.html)
  35. ## 概述
  36. <font style="color:rgb(52, 58, 64);">在本教程中，我们将向您展示如何将 Jupyter Lab 与 Quarto 配合使用。你将在 Jupyter Lab 中编辑代码和 Markdown，就像使用任何笔记本一样，并在工作时在 Web 浏览器中预览呈现的文档。</font>
  38. <font style="color:rgb(52, 58, 64);">以下是其外观的概述。</font>
  40. ![](https://cdn.nlark.com/yuque/0/2024/png/39191047/1721718471536-952d0fe4-4467-48ff-969f-bba27d96657d.png)
  42. <font style="color:rgb(52, 58, 64);">左边的笔记本</font>_<font style="color:rgb(52, 58, 64);">将呈现</font>_<font style="color:rgb(52, 58, 64);">为您在右边看到的 HTML 版本。这是 Quarto 发布的基本模型 - 获取源文档（在本例中为笔记本）并将其呈现为各种</font>[<font style="color:rgb(52, 58, 64);">输出格式</font>](https://quarto.org/docs/output-formats/all-formats.html)<font style="color:rgb(52, 58, 64);">，包括 HTML、PDF、MS Word 等。</font>
  44. **<font style="color:rgb(52, 58, 64);background-color:rgb(233, 242, 252);">注意</font>**
  46. <font style="color:rgb(52, 58, 64);">请注意，虽然本教程使用 Python，但使用 Julia（通过</font><font style="color:rgb(52, 58, 64);"> </font>[<font style="color:rgb(52, 58, 64);">IJulia</font>](https://julialang.github.io/IJulia.jl/stable/)<font style="color:rgb(52, 58, 64);"> </font><font style="color:rgb(52, 58, 64);">内核）也得到了很好的支持。有关更多详细信息，请参阅</font>[<font style="color:rgb(52, 58, 64);">有关使用 Julia</font>](https://quarto.org/docs/computations/julia.html)<font style="color:rgb(52, 58, 64);"> </font><font style="color:rgb(52, 58, 64);">的文章。</font>
  48. ## 渲染
  49. <font style="color:rgb(52, 58, 64);">首先，我们将在 Jupyter Lab 中打开一个笔记本 （） 并将其呈现为几种格式。如果要在自己的环境中逐步操作，请下载下面的笔记本。</font>`<font style="background-color:rgb(248, 249, 250);">hello.ipynb</font>`
  51. <font style="color:rgb(52, 58, 64);"></font>[<font style="color:rgb(52, 58, 64);">下载你好.ipynb</font>](https://quarto.org/docs/get-started/hello/_hello.ipynb)
  53. <font style="color:rgb(52, 58, 64);">然后，创建一个要在其中使用的新目录，将笔记本复制到此目录中，并在终端中切换到此目录。</font>
  55. <font style="color:rgb(52, 58, 64);">接下来，执行以下命令以安装 JupyterLab 以及教程中使用的包 （ 和 打开教程笔记本：</font>`<font style="background-color:rgb(248, 249, 250);">matplotlib</font>``<font style="background-color:rgb(248, 249, 250);">plotly),</font>`
  57. | 平台 | 命令 |
  58. | --- | --- |
  59. | Mac/Linux操作系统 | Terminal<br/>```plain python3 -m pip install jupyter jupyterlab python3 -m pip install matplotlib plotly python3 -m jupyter lab hello.ipynb ```  |
  60. | 窗户 | Terminal<br/>```plain py -m pip install jupyter jupyterlab py -m pip install matplotlib plotly py -m jupyter lab hello.ipynb ```  |
  63. <font style="color:rgb(52, 58, 64);">这是我们在 Jupyter 实验室的笔记本。</font>
  65. ```plain
  66. ---
  67. title: "Quarto Basics"
  68. format:
  69.   html:
  70.     code-fold: true
  71. jupyter: python3
  72. ---
  74. For a demonstration of a line plot on a polar axis, see @fig-polar.
  76. ```{python}
  77. #| label: fig-polar
  78. #| fig-cap: "A line plot on a polar axis"
  80. import numpy as np
  81. import matplotlib.pyplot as plt
  83. r = np.arange(0, 2, 0.01)
  84. theta = 2 * np.pi * r
  85. fig, ax = plt.subplots(
  86.   subplot_kw = {'projection': 'polar'} 
  87. )
  88. ax.plot(theta, r)
  89. ax.set_rticks([0.5, 1, 1.5, 2])
  90. ax.grid(True)
  91. plt.show()
  2. ![](https://cdn.nlark.com/yuque/0/2024/png/39191047/1721718470561-fb3d5116-879e-4d2d-9db9-598787dc23db.png)
  4. <font style="color:rgb(52, 58, 64);">接下来，在 Jupyter Lab 中创建一个新终端以用于 Quarto 命令。</font>
  6. ![](https://cdn.nlark.com/yuque/0/2024/png/39191047/1721718470117-57eb8b00-c50e-4d46-8f3d-fc5bc20cfefb.png)
  8. <font style="color:rgb(52, 58, 64);">最后，将笔记本呈现为几种格式。</font>
  10. <font style="color:rgb(52, 58, 64);">Terminal</font>
  12. ```plain
  13. quarto render hello.ipynb --to html
  14. quarto render hello.ipynb --to docx
请注意，目标文件（在本例中）应始终是第一个命令行参数。<font style="background-color:rgb(248, 249, 250);">hello.ipynb</font> 使用 Quarto 渲染 Jupyter 笔记本时，笔记本的内容（代码、Markdown 和输出）将转换为纯 Markdown，然后由 Pandoc 进行处理，从而创建完成的格式。

使用流程 - 图6

创作

该命令用于创建要分发的文档的最终版本。但是，在创作过程中，您将使用该命令。现在从终端试用 .<font style="background-color:rgb(248, 249, 250);">quarto render</font>``<font style="background-color:rgb(248, 249, 250);">quarto preview</font>``<font style="background-color:rgb(248, 249, 250);">hello.ipynb</font> Terminal quarto preview hello.ipynb 这将呈现您的文档，然后在 Web 浏览器中显示它。

使用流程 - 图7

您可能希望将 Jupyter Lab 和浏览器预览并排放置，以便在工作时查看更改。

使用流程 - 图8

要查看实时预览，请执行以下操作：
  1. 更改定义如下的代码行：<font style="background-color:rgb(248, 249, 250);">theta</font>
theta = 4 np.pi r
  1. 重新运行代码单元以生成绘图的新版本。
  2. 保存笔记本（预览将自动更新）。
这是使用 Quarto 进行创作的基本工作流程。一旦你对此感到满意，我们还建议安装 Quarto JupyterLab 扩展，它提供了在 JupyterLab 中使用 Quarto 的其他工具。 我们的笔记本中有几种不同类型的单元格，让我们对每种类型进行一些工作。

YAML 选项

您可能已经熟悉 Markdown 和代码单元格，但有一种新型单元格（“Raw”）用于文档级 YAML 选项。 
  1. ---
  2. title: "Quarto Basics"
  3. format:
  4.   html:
  5.     code-fold: true
  6. jupyter: python3
  7. ---

使用流程 - 图9

尝试将选项更改为 。<font style="background-color:rgb(248, 249, 250);">code-fold</font>``<font style="background-color:rgb(248, 249, 250);">false</font> plain format: html: code-fold: false 然后保存笔记本。您会注意到，代码现在显示在绘图上方，而以前它使用可用于显示它的代码按钮隐藏。

Markdown 单元格

Markdown 单元格包含原始 Markdown，将在渲染期间传递到 Quarto。您可以在这些单元格中使用任何有效的 Quarto Markdown 语法。在这里，我们指定一个标题和对在下面代码单元中创建的图形的交叉引用。 
  1. ## Polar Axis
  3. For a demonstration of a line plot on a polar axis, see @fig-polar.

使用流程 - 图10

尝试更改页眉并保存笔记本 - 预览将使用新的页眉文本进行更新。

代码单元

您可能已经熟悉代码单元，如下所示。 
  1. ```{python}
  2. #| label: fig-polar
  3. #| fig-cap: "A line plot on a polar axis"
  5. import numpy as np
  6. import matplotlib.pyplot as plt
  8. r = np.arange(0, 2, 0.01)
  9. theta = 2 * np.pi * r
  10. fig, ax = plt.subplots(
  11.   subplot_kw = {'projection': 'polar'} 
  12. )
  13. ax.plot(theta, r)
  14. ax.set_rticks([0.5, 1, 1.5, 2])
  15. ax.grid(True)
  16. plt.show()

```

使用流程 - 图11

但是在代码单元格的顶部有一些新的组件：和选项。单元格选项在 YAML 中使用特殊前缀的注释 （） 编写。<font style="background-color:rgb(248, 249, 250);">label</font>``<font style="background-color:rgb(248, 249, 250);">fig-cap</font>``<font style="background-color:rgb(248, 249, 250);">#|</font> 在此示例中，单元格选项用于使图形可交叉引用。尝试更改和/或代码，运行单元格，然后保存笔记本以查看更新的预览。<font style="background-color:rgb(248, 249, 250);">fig-cap</font> 您可以应用多种单元格选项来定制输出。我们将在下一个教程中深入探讨这些选项。

注意

对于图形来说，一个特别有用的单元格选项是 ，它使您能够为有视力障碍的用户向图像添加替代文本。请参阅 Amy Cesal 关于为数据可视化编写替代文本的文章以了解更多信息。<font style="background-color:rgb(248, 249, 250);">fig-alt</font> ## 下一步 您现在了解了创建和创作 Quarto 文档的基础知识。以下教程更深入地探讨了 Quarto：
  • 教程：计算 — 了解如何定制可执行代码块的行为和输出。
  • 教程：创作 — 详细了解输出格式和技术写作功能，如引文、交叉引用和高级布局。
此外，您可能希望安装 Quarto JupyterLab 扩展，它提供了用于在 JupyterLab 中使用 Quarto 的其他工具。