写在前面

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

::: block-1

目录

• 1 概述
• 2 输出格式
• 3 渲染
• 4 部分
• 5 方程
• 6 引文
• 7 交叉引用
• 8 标注
• 9 文章布局
• 10 发布
• 11 了解更多
  :::

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

1 概述

在本教程中，我们将向您展示如何在 RStudio 中创作 Quarto 文档。特别是，我们将讨论您可以使用相同源代码生成的各种文档格式，并向您展示如何添加目录、方程式、引文等组件。RStudio 中的可视化 Markdown 编辑器使许多此类任务变得更加容易我们将在本教程中重点介绍它的用途，但请注意，也可以在源代码编辑器中完成这些任务。

如果您想在自己的环境中逐步进行操作，请确保您已安装最新版本的 RStudio (v2023.06)。

2 输出格式

Quarto 支持将笔记本渲染为数十种不同的输出格式。默认情况下，使用 html 格式，但您可以在文档选项中指定替代格式（或多个格式）。

格式选项

您可以在创建新文档时选择要渲染 Quarto 文档的格式。要创建新文档，请转到 File > New File > Quarto Document… 或者，使用命令选项板（可通过 Ctrl+Shift+P 访问），搜索 Create a new Quarto document 并按回车键。

在 Title 字段中，为文档指定一个标题（例如，下面的屏幕截图显示 “Housing Prices”），并将您的姓名添加到 Author 字段中。接下来，您将为文档选择输出格式。默认情况下，RStudio 建议使用 HTML 作为输出，我们暂时保留该默认值。

将使用以下 YAML 创建一个新文档。

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
---

请注意，我们的格式选择 (HTML) 甚至没有反映在 YAML 中，因为它是 Quarto 文档的默认输出格式。但是，您可以直接编辑 YAML 来更改输出格式，例如转换为 PDF (pdf) 或 MS Word (docx)。将 format: pdf 添加到文档的 YAML 中，如下所示。

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
format: pdf
---

不幸的是，该文档没有内容，因此渲染它不会产生非常有趣的输出。为了更容易地演示我们想要在本教程中强调的所有功能，让我们关闭这个空文档并从其中包含一点内容的文档开始。如果您想在自己的环境中逐步进行操作，请下载下面的 Quarto 文档 (.qmd) 并在 RStudio 中打开它。

Download authoring.qmd: https://quarto.org/docs/get-started/authoring/_authoring.qmd

为了创建 PDFs，您需要安装最新的 LaTeX 发行版。我们推荐使用 TinyTeX（它基于 TexLive），您可以使用以下命令安装它：

quarto install tinytex

有关使用其他 LaTeX 发行版和 PDF 编译引擎的详细信息，请参阅有关 PDF Engines 的文章。

设置完 LaTeX 后，单击 Render（或使用键盘快捷键 ⇧⌘K）。我们建议还选中 Render on Save 框，以实时预览您的更改。如下所示，您应该在 RStudio 的查看器中看到渲染的 PDF。

接下来，让我们向 YAML 添加一个选项，例如将行号添加到代码块中（code-line-numbers：true）。将此选项添加到文档的 YAML 中，如下所示，注意缩进方案。在 format: 中我们的格式选择 pdf 是缩进的（有两个空格），后面跟着 : 表示将指定该格式的更多选项。在下一行中，进一步缩进两个空格，我们添加 code-line-numbers: true。

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
format:
  pdf:
    code-line-numbers: true
---

如果您之前选中了 Render on Save，则只需在进行此更改后保存文档即可进行实时预览。否则呈现文档以查看反映的更新，包括如下所示的目录。

revealjs 是一个令人难以置信的令人兴奋的格式选项，我们不会在本教程中详细介绍。是的，您也可以使用 Quarto 进行演示文稿！事实上，Quarto 支持多种用于创建演示文稿的格式，包括用于 HTML 幻灯片的 revealjs、用于 PowerPoint 的 pptx 以及用于 LaTeX/PDF 的 beamer。Presentations 文章详细介绍了如何使用 Quarto 创建幻灯片。

多种格式

您创建的某些文档只有一种输出格式，但在许多情况下，需要支持多种格式。让我们将 html 和 docx 格式添加到我们的文档中，并修改特定于每种格式的一些选项。

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
highlight-style: pygments
format:
  html: 
    code-fold: true
    html-math-method: katex
  pdf:
    geometry: 
      - top=30mm
      - left=30mm
  docx: default
---

这里有很多东西值得一看！让我们把它分解一下。前两行是通用文档元数据，与输出格式根本无关。

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
---

下一行是适用于所有格式的文档格式选项，这就是它在根级别指定的原因。

---
highlight-style: pygments
---

接下来，我们有 format 选项，我们在其中提供特定于格式的选项。

---
format:
  html: 
    code-fold: true
    html-math-method: katex
  pdf:
    geometry: 
      - top=30mm
      - left=30mm
  docx: default
---

html 和 pdf 格式各自提供一两个选项。例如，对于 HTML 输出，我们希望用户能够控制是否显示或隐藏代码 (code-fold: true) 并使用 katex 来处理数学文本。对于 PDF，我们定义了一些边距。 docx 格式有点不同 -- 它指定 docx: default。这表明我们只想使用该格式的所有默认选项。

3 渲染

单击 RStudio 中的 Render 按钮（或使用键盘快捷键 ⇧⌃K）会将文档渲染为 YAML 中列出的第一种格式。

请注意，Render 按钮还有一个下拉菜单，使您能够渲染为 YAML 前面列出的任何格式：

如果您想渲染为所有格式，可以使用 quarto 包来实现，它为 Quarto CLI 提供了 R 接口。例如，要渲染当前文档，请使用 quarto::quarto_render()。您还可以指定要呈现的文档的名称以及输出格式。

quarto::quarto_render(
  "authoring.qmd", 
  output_format = c("pdf", "html", "docx")
)

结果，您将看到三个新文件出现在“Files”窗格中：

• authoring.docx
• authoring.html
• authoring.pdf

4 部分

您可以使用目录和/或章节编号来使读者更轻松地浏览您的文档。通过将 toc 和/或 number-sections 选项添加到文档选项来执行此操作。请注意，这些选项通常在根级别指定，因为它们在所有格式之间共享。

---
title: "Housing Prices"
author: "Mine Çetinkaya-Rundel"
toc: true
number-sections: true
highlight-style: pygments
format:
  html: 
    code-fold: true
    html-math-method: katex
  pdf:
    geometry: 
      - top=30mm
      - left=30mm
  docx: default
---

这是该文档呈现为 HTML 时的样子。

有很多选项可用于控制目录和章节编号的行为方式。有关更多详细信息，请参阅输出格式文档（例如 HTML、PDF、MS Word）。

5 方程

如果您使用可视化编辑器模式，则可以使用 Insert Anything 工具将 LaTeX 方程添加到 RStudio 中的 Quarto 文档中。您可以在空块的开头使用 / 或在其他任何地方使用 Cmd+/ 来访问它。

显示方程（在新行中）用 $$...$$ 分隔，而内联方程用 $...$ 分隔。添加以下内容作为文档中的显示数学。

$$
price = \hat{\beta}_0 + \hat{\beta}_1 \times area + \epsilon
$$

当您在编辑器中键入教程时，RStudio 会显示教程的渲染版本。有关更多详细信息，请参阅有关 markdown equations 的文档。

6 引文

Insert Anything 工具还可用于在文档中插入引文。

在下一个窗口中，您可以通过各种来源插入引文，包括您的文档书目、Zotero 个人或团队 libraries、DOI (Document Object Identifier) references 以及 Crossref、DataCite 或 PubMed 的搜索。您可以在此处找到有关使用可视化编辑器引用的更多信息。

选择左侧的 From DOI，然后将 DOI 10.1093/comjnl/27.2.97 复制并粘贴到搜索栏中，然后点击 Search。然后，选择找到的 reference，并将其 insert 到您的文档中。

如果这是您添加到文档中的第一个 citation，RStudio 将自动为您创建一个参考书目文件。默认情况下，该文件名为 references.bib，RStudio 还会将 bibliography: references.bib 添加到文档的 YAML 元数据中。

请注意，参考书目中的项目是使用 @citeid 语法引用的。将以下文本添加到您的文档中。

We're going to do this analysis using literate programming [@knuth1984].

参考文献将包含在文档的末尾，因此我们在笔记本底部包含一个 ## References。您还可以通过单击三个点 (...) 来编辑其属性，将 .unnumbered 类添加到此部分。

这是该文档渲染后的样子（删除了中间部分以突出显示相关部分）。

@ 引用语法非常灵活，包括对前缀、后缀、定位符和文本内引用的支持。请参阅有关 Citations and Footnotes 的文档以了解更多信息。

7 交叉引用

交叉引用通过提供数字、表格、方程和章节的编号参考和超链接，使读者能够更轻松地浏览文档。可交叉引用的实体通常需要标签（唯一标识符）和标题。

例如，要向之前插入的方程添加标签，请单击三个点来编辑其属性并使用建议的格式（以 #eq- 开头）来标记方程。

然后，使用可视化编辑器中的 Insert Anything 工具添加交叉引用。您可以添加诸如 "We can fit a simple linear regression model of the form shown in" 之类的句子来将交叉引用置于上下文中，然后将引用添加到该句子的末尾。

在 Insert Cross Reference 菜单中，导航到左侧所需的交叉引用实体，然后选择之前标记的方程。

或者，开始在可视化编辑器中键入要引用的方程的标签，自动填充工具将显示交叉引用以供选择。

下面我们使用您一直使用的文档中的片段来说明交叉引用各种类型的实体。

We present the results of exploratory data analysis in @sec-eda and the regression model in @sec-model.


@fig-scatterplot displays the relationship between these two variables in a scatterplot.


@tbl-stats displays basic summary statistics for these two variables.


We can fit a simple linear regression model of the form shown in @eq-slr.

该示例包括交叉引用的部分、图形和方程。下表总结了我们如何表达这些内容。

请参阅有 Cross References 的文章以了解更多信息，包括如何自定义标题和参考文本（例如使用“Fig.”而不是“Figure”）。

8 标注

标注是一种很好的方式，可以吸引人们对某些概念的额外关注，或者更清楚地表明某些内容是补充性的或仅适用于某些场景。

标注是具有特殊标注属性的 Markdown div。我们可以使用 Insert Anything 工具插入标注。

在随后的对话框中，您可以选择五种标注类型之一（注释、提示、重要、注意或警告），自定义其外观（默认、简单或最小），并决定是否要显示图标。

然后，尝试在标注框中插入以下文本。

This is a pretty incomplete analysis, but hopefully the document provides a good overview of some of the authoring features of Quarto!

这是可视化编辑器中标注的样子。

这是输出文档中渲染的标注。

您可以在 Callouts 文档中了解有关不同类型标注及其外观选项的更多信息。

9 文章布局

Quarto 文章正文的默认宽度约为 700 像素。选择此宽度是为了优化可读性。这通常会在文档页边距中留下一些可用空间，您可以通过多种方式利用该空间。

我们可以使用 column: page-right 单元选项来指示我们希望图形占据屏幕的整个宽度，并带有一些插图。继续并将此代码块选项添加到标记为 fig-histogram 的代码块中。

#| label: fig-histogram
#| fig-cap: "Histograms of individual variables"
#| fig-subcap:
#|   - "Histogram of `price`s"
#|   - "Histogram of `area`s" 
#| layout-ncol: 2
#| column: page-right

以下是文档的相关部分渲染后的样子。

您可以在页边空白处找到引文、脚注和旁白。您还可以为图形、表格或其他内容定义自定义列跨度。有关更多详细信息，请参阅有关 Article Layout 的文档。

10 发布

将文档渲染为 HTML 后，您只需单击编辑器工具栏或预览窗口上的 Publish 按钮即可将其发布到 RPubs（RStudio 的一项免费服务，用于在网络上共享文档）。或者，您可以使用 quarto::quarto_publish_doc() 函数。

quarto::quarto_publish_doc(
  "authoring.qmd", 
  server = "rpubs.com"
  )

其他可能的发布选项包括 RStudio Connect 和 ShinyApps 以及 GitHub Pages、Netlify 等。Publishing HTML 文章更详细地概述了您的发布选项。

如果您按照本教程的步骤进行操作，那么您现在应该拥有一个 Quarto 文档，该文档实现了我们所涵盖的所有内容。否则，您可以下载下面的 computations.qmd 的完整版本。

Download authoring-complete.qmd: https://quarto.org/docs/get-started/authoring/_authoring-complete.qmd

11 了解更多

您现在已经了解了使用 Quarto 的基础知识！一旦您能够轻松地创建和自定义文档，这里还有一些需要探索的事情：

• Presentations 使用您为创建文档所学的相同语法来创作 PowerPoint、Beamer 和 Revealjs 演示文稿。
• Websites 将文档集发布为网站。网站支持多种形式的导航和全文搜索。
• Blogs 创建一个包含“关于”页面、灵活的帖子列表、类别、RSS 源和二十多个主题的博客。
• Books 创建印刷版（PDF、MS Word）和在线版（HTML、ePub）格式的书籍和手稿。
• Interactivity 包括交互式组件，以帮助读者更深入地探索您所呈现的概念和数据。

详细教程请参考 quarto Guide：https://quarto.org/docs/guide/

<center><strong>结束</center></strong>

本文由mdnice多平台发布