quarto 教程 1：Hello, Quarto

「写在前面」

学习一个软件最好的方法就是啃它的官方文档。本着自己学习、分享他人的态度，分享官方文档的中文教程。软件可能随时更新，建议配合官方文档一起阅读。

---

目录

• 1 Quarto 介绍
• 2 Quarto 安装
• 3 学习概述
• 4 渲染
• 5 创作
• 6 Quarto 如何工作
• 7 下一步

官网教程：https://quarto.org/docs/get-started/

1 Quarto 介绍

Quarto 是一个开源科学和技术出版系统

Quarto 具有以下功能：

• 作者可以使用 Jupyter notebooks 或在您喜欢的编辑器中使用纯文本 Markdown 进行创作。
• 使用 Python、 R、 Julia 和 Observable 创建动态内容。
• 发表可复制的、高质量的 articles、presentations、dashboards、websites、blogs、books 以 HTML、PDF、MS Word、ePub 等格式。
• 通过发布到 Posit Connect、 Confluence 或其他发布系统，在整个组织范围内共享知识和见解。
• 使用 Pandoc Markdown 进行编写，包括方程、引文、交叉引用、图形面板、标注、高级布局等。

2 Quarto 安装

安装 Quarto: https://quarto.org/docs/get-started/

3 学习概述

Quarto 是 Posit 的 R Markdown 的 multi-language, next-generation 版本，包含数十个新特性和功能，同时能够在不进行修改的情况下渲染大多数现有的 Rmd 文件。

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

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

这是 Quarto 出版的基本模型 - 获取源文档并将其呈现为各种输出格式。

如果您想在深入学习本教程之前观看有关 Quarto 的视频介绍，请观看 Get Started with Quarto，您可以在其中看到使用可执行代码块创作 Quarto 文档、渲染为多种格式，包括 revealjs presentations、创建一个 website，并在 QuartoPub 上发布。

如果您想在自己的环境中学习本教程，请按照下面列出的步骤操作。

1. 下载并安装最新版本的 RStudio (v2023.06):

https://posit.co/download/rstudio-desktop/

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

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

3. 下载下面的 Quarto 文档 ( .qmd)，在 RStudio 中打开它，然后单击 Render。

https://quarto.org/docs/get-started/hello/rstudio/_hello.qmd

4 渲染

使用 RStudio IDE 中的「Render」按钮渲染文件并通过单击或键盘快捷键 (⇧⌘K) 预览输出。

如果您希望在保存时自动渲染，可以选中编辑器工具栏上的「Render on Save」选项。每当您重新渲染文档时，预览都会更新。并排预览适用于 HTML 和 PDF 输出。

请注意，文档也可以通过 「quarto」 包从 R 控制台呈现：

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

渲染时，Quarto 会生成一个新文件，其中包含 .qmd 文件中选定的文本、代码和结果。新文件可以是 HTML、PDF、MS Word document、presentation、website、book、interactive document 或其他格式。

5 创作

在下图中，我们可以在 RStudio 编辑器的两种模式下看到同一个文档：可视化编辑器（左侧）和源码编辑器（右侧）。 RStudio 的可视化编辑器为 Markdown 提供了所见即所得的创作体验。对于格式设置（例如，粗体文本），您可以使用工具栏、键盘快捷键 (⌘B) 或 Markdown 结构 (「bold」)。该文档底层的纯文本源代码是为您编写的，您可以通过切换到源码模式进行编辑来随时查看/编辑它。您可以通过单击编辑器工具栏中的 「Source」 和 「Visual」（或使用键盘快捷键 ⌘⇧ F4）在这两种模式之间来回切换。

接下来，让我们将注意力转向 Quarto 文档的内容。该文件包含三种类型的内容：一个 YAML header、code chunks 和 Markdown 文本。

YAML header

两端由三个破折号 (---) 分隔的（可选）YAML header。

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

渲染时，title: "Hello, Quarto" 将出现在渲染文档的顶部，其字体大小比文档的其余部分更大。另外两个 YAML fields 表示输出应为 html 格式，并且默认情况下文档应在可视化编辑器中打开。

YAML 的基本语法使用格式为 key: value 的键值对。文档 headers 中常见的其他 YAML fields 包括 author, subtitle, date 等元数据以及 theme, fontcolor, fig-width 等自定义选项。可用的 YAML fields 根据文档格式的不同而有所不同，HTML 文档的所有可用 YAML fields 请参考官方文档：

https://quarto.org/docs/reference/formats/html.html

Code chunks

R code chunks 用 {r} 标识，带有（可选）chunk options，采用 YAML 样式，由 #| 标识在该行的开头。

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

library(tidyverse)
library(palmerpenguins)
```

在这种情况下，code chunks 的 label 是 load-packages，我们将 include 设置为 false 来指示我们不希望该 chunk 本身或其任何输出出现在渲染的文档中。

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

Markdown text

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

Quarto 对文本使用 Markdown 语法。如果使用可视化编辑器，您不需要学习太多 Markdown 语法来创作文档，因为您可以使用菜单和快捷方式添加标题、粗体文本、插入表格等。如果使用源码编辑器，您可以可以使用像 ##、**bold** 等 Markdown 表达式来实现这些。

6 Quarto 如何工作

当您渲染 Quarto 文档时，首先 knitr 执行所有代码块并创建一个新的 Markdown (.md) 文档，其中包括代码及其输出。生成的 Markdown 文件然后由 pandoc 处理，创建最终的格式。渲染按钮封装了这些操作并以适合您的顺序执行它们。

7 下一步

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

• Tutorial: Computations — 了解如何定制可执行代码块的行为和输出。
• Tutorial: Authoring — 详细了解输出格式和技术写作功能，例如引文、交叉引用和高级布局。

这些内容将在后面的推文中介绍。

「结束」

本文由 mdnice 多平台发布