教程：你好，Quarto

概述

在本教程中，我们将向你展示如何将Quarto与Neovim一起使用。虽然我们在这里涵盖了基础知识，但你还需要查看关于将Neovim与Quarto一起使用的文章，以了解更多关于安装、使用和为Quarto定制Neovim的信息。

如果你已经按照自己的喜好配置了Neovim，你可能只想添加quarto-nvim插件，并仅参考本指南以获得灵感和了解可能性。 但如果你对Neovim完全陌生，或者只是想尝试一个已经为数据科学设置了配置的Quarto，你应该前往这个启动配置。这也是我们将在本教程中使用的内容。

Note

Neovim是一个高度可定制的编辑器。 如此之高以至于Neovim核心成员TJ Devries最近创造了个人开发环境（PDE）1这个术语，以与集成开发环境（IDE）如VS Code和RStudio区分开来。

开箱即用的neovim相当简约。 为了高效工作并获得所有不错的功能，你必须配置它。 你必须让它成为你自己的。 如果这种方法听起来吸引人，请继续阅读。 欢迎来到兔子洞。🐰

你还可以观看这个视频，以快速了解如何与这篇文字一起开始使用启动配置。

Quarto Neovim插件旨在不重新发明轮子。 现有的Neovim生态系统中的插件被用来提供完整的体验。 quarto-nvim提供并由启动配置中的插件增强的一些功能包括：

  • Quarto文档的预览。
  • 对Markdown和嵌入式语言的语法高亮。
  • 对嵌入式语言（例如Python、R、Julia等）的自动补全。
  • 运行单元格和选中行的命令和快捷键绑定。
  • 对参考文献引用、文件路径、LaTeX数学符号、表情符号的自动补全。
  • 可选的拼写检查和自动补全。
  • 代码片段。
  • 将代码块导出为独立脚本。

有关所有细节，请参阅将Neovim与Quarto一起使用的文章。

基本工作流程

Quarto .qmd 文件包含Markdown和可执行代码单元格的组合。 以下是使用Neovim编辑和预览.qmd文件时可能的样子：

三个窗口并排排列。左边的窗口是Neovim中打开的qmd文件。右上角的窗口是一个网页浏览器。qmd文档的内容由Quarto在浏览器窗口中渲染。第三个窗口是一个渲染的图形，显示了在qmd文件中执行代码块的输出。

你看到的左边.qmd文件被渲染为你看到的右边HTML文档。 这是Quarto发布的基本模型——取一个源文档并将其渲染为多种输出格式，包括HTML、PDF、MS Word等。

教程将使用matplotlib和plotly Python包——你可以用来安装它们的命令在下面的表格中给出。

平台 命令
Mac/Linux 
Terminal
python3 -m pip install jupyter matplotlib plotly
Windows 
Terminal
py -m pip install jupyter matplotlib plotly
Note

请注意，虽然本教程使用Python，但使用Julia（通过IJulia内核）或使用R（通过knitr包）也得到了很好的支持。 有关更多详细信息，请参阅使用Julia和使用R的文章。

渲染和预览

我们将从一个简单的示例（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()

要渲染并预览，请按 `:` 进入命令模式并输入 **QuartoPreview** 命令（如果有自动补全功能，可以按 <kbd>tab</kbd> 键）。
在kickstarter配置中，有更多以 <kbd>space q</kbd>（空格键后跟 q，在正常模式下）开头的快捷键。

### 工作原理

当你使用 Quarto 渲染 `.qmd` 文件时，可执行代码块由 Jupyter 处理，然后将代码、Markdown 和输出结果组合转换为普通 Markdown。
然后，这个 Markdown 由 [Pandoc](http://pandoc.org/) 处理，创建最终的格式。

![](images/qmd-how-it-works.png){alt="" fig-alt="工作流程图，从 qmd 文件开始，经过 Jupyter，然后是 md，然后是 pandoc，最后生成 PDF、MS Word 或 HTML。" fig-align="left"}

### 创作

让我们尝试做一个小改动然后重新渲染：

1. 将定义 `theta` 的代码行改为如下：

    ``` python
    theta = 4 * np.pi * r
    ```

2. 使用 `:w` 在正常模式下保存文件，或使用 `ctrl-s` ^[如果你使用的是 kickstarter 配置——否则 `ctrl-s` 会让你的终端进入等待模式，直到你按下 `ctrl+q`，这可能会让人困惑]

文档被渲染，浏览器预览也会更新。
这是使用 Quarto 进行创作的基本工作流程。

### 运行单元格

无需完全渲染文档即可迭代代码单元格。通过提供的配置，我们可以使用领导者键（`<space>`）后跟`c`（代表代码），然后是`p`（代表Python）或`i`（代表IPython）来打开我们选择的终端。

如果在按键之间稍作等待，屏幕底部会弹出一个小窗口，告知您现有的键绑定：

![](/docs/get-started/hello/images/neovim-open-terminal.png)

我们可以使用`ctrl`加上vim方向键在代码和终端之间导航，并通过进入此终端缓冲区的插入模式向Python REPL输入命令。

要从quarto向Python REPL发送代码，我们导航到一个代码块并按下`<space><cr>`（空格键后跟回车键）。负责将代码发送到各个地方的插件[vim-slime](https://github.com/jpalardy/vim-slime)会提示我们选择将代码发送到哪个终端，并预先填写我们最近创建的终端。

![](/docs/get-started/hello/images/neovim-send-code.png)

如果您想像在RStudio中一样使用<kbd>ctrl+Enter</kbd>发送代码，您需要告诉终端模拟器发送正确的键码。例如，在[kitty](https://github.com/kovidgoyal/kitty)终端中，配置如下所示：

```
map ctrl+shift+enter no_op
map shift+enter send_text all \x1b[13;2u
map ctrl+enter send_text all \x1b[13;5u
```

这是kickstarter配置所测试的内容。


`hello.qmd` 中有几种不同类型的内容，让我们逐一进行处理。

## YAML 选项

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

``` yaml
---
title: "Quarto 基础"
format:
  html:
    code-fold: true
jupyter: python3
---
```

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

``` yaml
format: 
  html:
    code-fold: false
```

然后保存文件重新渲染文档。
你会注意到代码现在显示在图表上方，而之前它是通过一个 **Code** 按钮隐藏的，可以用来显示代码。

叙述性内容使用 Markdown 编写。
这里我们指定了一个标题，并交叉引用下面代码单元格中创建的图表。

``` markdown
## 极坐标轴

关于极坐标轴上的线条图演示，请参见 @fig-polar。
```

尝试更改标题并重新渲染——预览将更新为新的标题文本。

## 代码单元格

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

```` markdown
```{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 和/或代码，然后重新渲染以查看更新后的预览。

有许多 单元格选项 可以应用来定制你的输出。 我们将在下一个教程中深入探讨这些选项。

Note

对于图表来说，一个特别有用的单元格选项是 fig-alt，它允许你为图像添加替代文本，以便于视觉障碍用户使用。 参见 Amy Cesal 的文章 Writing Alt Text for Data Visualization 以了解更多。

下一步

你现在知道了创建和编辑 Quarto 文档的基础知识。以下教程将更深入地探讨 Quarto：

  • 教程：计算 —— 学习如何定制可执行代码块的行为和输出。

  • 教程：创作 —— 了解更多关于输出格式和技术写作功能，如引用、交叉引用和高级布局。

参见文章 使用 Neovim 与 Quarto 以了解更多关于安装、使用和自定义 Neovim 进行 Quarto 的信息。

Footnotes

  1. 在这个视频中↩︎