教程：你好，Quarto

概述

Quarto 是一个多语言的、下一代的 R Markdown 版本，由 Posit 开发，包含了数十项新功能和能力，同时能够无需修改地渲染大多数现有的 Rmd 文件。

在本教程中，我们将向您展示如何使用 RStudio 与 Quarto。您将在 RStudio 中编辑代码和 Markdown，就像您在任何计算文档（例如，R Markdown）中所做的那样，并在您工作时在 Viewer 选项卡中预览渲染的文档。

以下是一个扩展名为 .qmd 的 Quarto 文档（左侧），以及其渲染为 HTML 的版本（右侧）。您还可以选择将其渲染为其他格式，如 PDF、MS Word 等。

RStudio 中打开了一个标题为“企鹅，认识 Quarto！”的 Quarto 文档，左侧是文档，右侧是渲染版本。

这是 Quarto 发布的基本模型——获取源文档并将其渲染为多种输出格式。

如果您想在深入教程之前通过视频介绍了解 Quarto，请观看 开始使用 Quarto，您可以在其中预览如何使用可执行代码块创作 Quarto 文档，渲染为多种格式（包括 revealjs 演示文稿），创建网站，并在 QuartoPub 上发布。

如果您想在自己的环境中跟随本教程，请按照以下步骤操作。

  1. 下载并安装最新版本的 RStudio（v2023.12）：

    下载 RStudio v2023.12

  2. 确保您已安装 tidyverse 和 palmerpenguins 包：

    install.packages("tidyverse")
install.packages("palmerpenguins")

  3. 下载下面的 Quarto 文档（.qmd），在 RStudio 中打开它，并点击 渲染。

    下载 hello.qmd

渲染

使用 RStudio IDE 中的 渲染按钮，通过单击或键盘快捷键（⇧⌘K）渲染文件并预览输出。

RStudio 文本编辑器的顶部，渲染按钮以紫色框突出显示。

如果您更喜欢在保存时自动渲染，可以在编辑器工具栏中勾选“保存时渲染”选项。每次重新渲染文档时，预览都会更新。并排预览适用于 HTML 和 PDF 输出。

RStudio 文本编辑器的顶部，保存时渲染复选框已勾选并以紫色框突出显示。

请注意，文档也可以通过 quarto 包从 R 控制台渲染：

install.packages("quarto")
quarto::quarto_render("hello.qmd")

在渲染时，Quarto 会生成一个包含所选文本、代码和结果的新文件。新文件可以是 HTML、PDF、MS Word 文档、演示文稿、网站、书籍、交互式文档 或 其他格式。

创作

在下图中，我们可以看到 RStudio 编辑器的两种模式下的相同文档：视觉模式（左侧）和源代码模式（右侧）。RStudio 的 视觉编辑器 为 Markdown 提供了一种 WYSIWYM 创作体验。对于格式化（例如，加粗文本），您可以使用工具栏、键盘快捷键（⌘B）或 Markdown 结构（**bold**）。文档的纯文本源代码会为您编写，您可以随时切换到源代码模式进行查看/编辑。您可以通过点击编辑器工具栏中的 源代码 和 视觉（或使用键盘快捷键 ⌘⇧ F4）在这两种模式之间切换。 左侧：视觉编辑器中的文档。右侧：源代码编辑器中的同一文档。视觉/源代码编辑器切换在两个文档中都突出显示，标记它们当前的状态。显示的文档是本页之前图像中的“Hello Quarto”文档。

接下来，让我们把注意力转向 Quarto 文档的内容。 文件包含三种类型的内容：YAML 头、代码块和 Markdown 文本。

YAML 头

由三个破折号（---）分隔的（可选）YAML 头。

---
title: "Hello, Quarto"
format: html
editor: visual
---

渲染时，title，即 "Hello, Quarto"，将以比文档其余部分更大的字体大小出现在渲染文档的顶部。 其他两个 YAML 字段表示输出应为 html format，并且文档默认应在 visual editor 中打开。

YAML 的基本语法使用键值对格式 key: value。 在文档头中常见的其他 YAML 字段包括元数据，如 author、subtitle、date，以及自定义选项，如 theme、fontcolor、fig-width 等。 你可以在这里找到所有适用于 HTML 文档的可用 YAML 字段。 可用的 YAML 字段因文档格式而异，例如，参见这里了解适用于 PDF 文档的 YAML 字段，以及这里了解适用于 MS Word 的 YAML 字段。

代码块

带有 {r} 标识的 R 代码块，可以选择性地使用 YAML 风格的代码块选项，以 #| 开头。

```{r}
#| label: load-packages
#| include: false

library(tidyverse)
library(palmerpenguins)
```

在这种情况下，代码块的 label 为 load-packages，我们将 include 设置为 false，以指示我们不希望在渲染文档中包含该代码块本身或其任何输出。

除了渲染整个文档以查看代码块的结果外，你还可以通过点击 图标或键盘快捷键（⇧⌘⏎）在 RStudio 编辑器中交互式地运行每个代码块。 RStudio 将执行代码并在文件内联或控制台中显示结果，具体取决于你的偏好。

背景中，hello.qmd中的代码块标记为plot-penguins。代码块部分被其输出覆盖，这是一个散点图，显示了企鹅喙长和鳍长之间的关系，按物种着色。运行代码块的按钮被突出显示，箭头指向图表，显示点击按钮会生成图表。

Markdown 文本

带有格式的文本，包括节标题、超链接、嵌入的图像和内联代码块。

链接的示例文档中标题为“Penguins, meet Quarto!”的文本部分，带有注释“文本”。

Quarto 使用 Markdown 语法来处理文本。 如果在视觉编辑器中使用，你不需要学习太多 Markdown 语法来编写文档，因为你可以使用菜单和快捷键来添加标题、加粗文本、插入表格等。 如果在源代码编辑器中使用，你可以通过 Markdown 表达式（如 ##、**bold** 等）来实现这些操作。

工作原理

当你渲染一个 Quarto 文档时，首先 knitr 执行所有代码块并创建一个新的 Markdown（.md）文档，其中包含代码及其输出。 生成的 Markdown 文件随后由 pandoc 处理，生成最终格式。 渲染按钮封装了这些操作，并按正确的顺序为你执行它们。

工作流程图，从 qmd 文件开始，然后是 knitr，然后是 md，然后是 pandoc，最后是 PDF、MS Word 或 HTML。

下一步

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

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

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