JupyterLab

概述

Quarto 可以渲染以纯文本形式（.qmd）或普通笔记本文件（.ipynb）表示的 Jupyter 笔记本。使用 .ipynb 的一个好处是你可以使用 JupyterLab 作为你的编辑器。

以下是 JupyterLab 中的“Hello, Quarto”示例，来自主页：

一个 Jupyter 笔记本，从上到下依次是一些 yaml 前言、一个章节标题、一个代码块以及代码块的输出。内容与本网站'欢迎'页面的第一部分相同。

如果你查看源代码，你会注意到 YAML 选项既在文档顶部提供，也在代码单元格内提供。我们将在下面更详细地描述如何使用 YAML 选项。

工作流程

在 JupyterLab 中编写 Quarto 笔记本的最佳工作流程是从终端运行 quarto preview 命令：

Terminal
quarto preview notebook.ipynb

笔记本将被渲染，并打开一个带有“实时预览”的网络浏览器。将此浏览器定位，以便在你编辑和保存笔记本时可以看到它：

两个并排排列的网络浏览器窗口。左边的窗口是 JupyterLab 窗口。这个 Jupyter 文档的内容由 Quarto 在右边的窗口中渲染。

每次在 JupyterLab 中保存时，预览都会自动更新。你可以对 HTML 和 PDF 输出使用 quarto preview。

在上面的截图中，你会注意到我们在 JupyterLab 终端窗口中运行了 quarto preview——这通常是推荐的，这样你可以在渲染发生时看到进度和错误信息。

预览使用文档中指定的默认格式——要使用替代格式，请将 --to 选项传递给 quarto preview。例如：

Terminal
quarto preview notebook.ipynb --to pdf

注意，如果你正在编写一本书或网站，你也可以在项目目录上使用 quarto preview，这将创建整个项目的实时预览。

运行 JupyterLab

要运行 JupyterLab，请在你使用 Quarto 的 shell 中调用 jupyter 模块：

平台 命令
Mac/Linux 
Terminal
python3 -m jupyter lab
Windows 
Terminal
py -m jupyter lab

不带预览的渲染

你可以使用 quarto render 命令在不预览的情况下渲染笔记本（或一组笔记本）：

Terminal
quarto render notebook.ipynb

使用 --to 参数渲染为特定格式：

Terminal
quarto render notebook.ipynb --to docx

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

JupyterLab 扩展

Quarto JuptyerLab 扩展使使用 Quarto markdown 的 JupyterLab 笔记本能够正确显示 markdown 单元格的内容。例如，当安装了 Quarto JupyterLab 扩展时，你的笔记本将显示 Callouts、Divs、Mermaid 图表等元素的渲染预览，以及其他 Quarto 元素（包括文档前言作为标题块）。

你可以在 Quarto JupyterLab 扩展 文档中阅读更多关于安装扩展的信息。

YAML 前言

你的笔记本的第一个单元格应该是一个包含文档标题、作者以及你需要指定的任何其他选项的 Raw 单元格。请注意，你可以使用笔记本工具栏将单元格类型切换为 Raw：

JupyterLab 文档的顶部部分。有一个包含 yaml 前言的 Raw 单元格。

在这个例子中，我们指定我们希望代码默认折叠显示。有 YAML 选项可以控制文档渲染的许多其他方面。有关更多详细信息，请参阅关于 创作 和 输出格式 的文档。

Markdown 单元格

以下是 markdown 单元格的底层代码：

一个包含 Markdown 单元格的 JupyterLab 文档片段。该单元格包含一些用 Markdown 编写的文本。 请注意，Markdown 中包含了一个 Quarto 交叉引用（@fig-polar）。任何有效的 Pandoc Markdown 语法都可以包含在 Markdown 单元格中。

输出选项

Quarto 使用带有特殊前缀（#|）的注释来表示单元格选项。在这里，我们指定了 label 和 fig-cap 选项，以便可以从单元格生成的图表进行交叉引用。

JupyterLab 文档的一个片段，包含一个代码单元格。在代码之前，单元格顶部是 Quarto 块选项 '#| label: fig-polar' 和 '#| fig-cap: 极坐标轴上的线图'。

请注意，选项必须出现在单元格的最开始。与文档前言一样，选项名称/值使用 YAML 语法。

有许多可用的输出选项，包括可选地隐藏代码、警告和/或输出的选项。有关更多详细信息，请参阅 输出选项 的文档。

单元格执行

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

Terminal
quarto render notebook.ipynb --execute

你也可以在笔记本的 YAML 前文中指定这种行为：

---
title: "My Notebook"
execute: 
  enabled: true
---

还有许多其他可用的执行选项（例如控制缓存、优化内核启动时间等）。在 执行选项 中了解更多关于这些选项的信息。

纯文本编辑

也可以以纯文本 Markdown 格式编辑 Jupyter 笔记本。如果您的笔记本中叙述多于代码，或者您希望使用更便于版本控制的文件格式，您可能会更喜欢这种方式。

以下是前面示例中使用的笔记本的纯文本 Markdown 版本：

---
title: "Matplotlib 演示"
author: "Norah Smith"
date: "2021/5/22"
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()
```

请注意，我们在 YAML 前言中添加了 jupyter: python3 选项，以指示使用哪个 Jupyter 内核进行渲染。您可以使用以下命令渲染此文档：

终端
quarto render basics-jupyter.qmd

嵌入代码块的 Markdown 文件应使用 .qmd 文件扩展名。

Tip

如果您主要在 .qmd 文件中工作，您应该考虑使用 RStudio，它完全支持使用 Python 和 Jupyter 编辑 .qmd 文件（包括代码补全、逐单元格执行和并排预览）。有关更多详细信息，请参阅关于使用 RStudio 的文章。

转换笔记本

您可以使用 quarto convert 命令在 .ipynb 和 .qmd 笔记本表示之间进行转换。例如：

终端
quarto convert basics-jupyter.ipynb # 转换为 qmd
quarto convert basics-jupyter.qmd   # 转换为 ipynb

有关转换笔记本的更多详细信息，请参阅 quarto convert help。

Jupytext

您可以使用 Jupytext 维护 .qmd 和 .ipynb 文件的并行同步版本。在 https://jupytext.readthedocs.io/en/latest/ 了解更多关于 Jupytext 的信息。