教程：撰写
VS Code
Jupyter
RStudio
Neovim
编辑器
概述
在本教程中，我们将向您展示如何在 RStudio 中编写 Quarto 文档。 特别是，我们将讨论如何使用相同的源代码生成各种文档格式，并向您展示如何添加目录、方程、引用等组件。 RStudio 中的可视化 Markdown 编辑器使得许多这些任务变得更加容易，因此我们将在本教程中突出其使用，但请注意，也可以在源代码编辑器中完成这些任务。
如果您希望在自己的环境中一步步跟随操作，请确保您已安装 最新版本 的 RStudio（v2023.12），您可以在此下载。
输出格式
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 中打开它。
为了创建 PDF，您需要安装一个最近的 LaTeX 发行版。 我们推荐使用基于 TexLive 的 TinyTeX，您可以使用以下命令安装它：
Terminal
quarto install tinytex有关使用其他 LaTeX 发行版和 PDF 编译引擎的详细信息，请参阅PDF 引擎文章。
一旦设置好 LaTeX，点击 
Render（或使用键盘快捷键 ⇧⌘K）。 我们还建议勾选 Render on Save 以实时预览您的更改。 如下图所示，您应该会在 RStudio 的 Viewer 中看到渲染的 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。演示文稿文章详细介绍了如何使用Quarto创建幻灯片。
多种格式
你创建的某些文档可能只有单一的输出格式，但在许多情况下，支持多种格式是可取的。让我们为文档添加html和docx格式，并修改每个格式特有的选项。
---
title: "房价"
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: "房价"
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。这表明我们只想使用该格式的所有默认选项。
渲染
在RStudio中点击 渲染按钮（或使用快捷键⇧⌘K）将文档渲染为YAML中列出的第一个格式。
请注意， 渲染按钮还有一个下拉菜单，使你可以渲染到YAML前文中列出的任何格式：
如果你想渲染到所有格式，可以使用quarto包，它提供了Quarto CLI的R接口。例如，要渲染当前文档，使用quarto::quarto_render()。你还可以指定要渲染的文档名称以及输出格式。
quarto::quarto_render(
"authoring.qmd",
output_format = c("pdf", "html", "docx")
)结果是，你会在“文件”窗格中看到三个新文件出现：
authoring.docxauthoring.htmlauthoring.pdf
章节
你可以使用目录和/或章节编号来方便读者浏览你的文档。通过在文档选项中添加toc和/或number-sections选项来实现这一点。请注意，这些选项通常在根级别指定，因为它们适用于所有格式。
---
title: "房价"
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）以获取更多详细信息。
方程
如果你使用的是可视化编辑器模式，你可以在RStudio中通过插入任何内容工具将LaTeX方程添加到Quarto文档中。你可以在空块的开头使用/或在其他任何地方使用Cmd+/来访问它。
显示方程（在新行中）使用$$…$$分隔，而行内方程使用$…$分隔。将以下内容作为显示方程添加到文档中。
price = \hat{\beta}_0 + \hat{\beta}_1 \times area + \epsilon当你在编辑器中输入时，RStudio会显示教程的渲染版本。有关更多详细信息，请参阅markdown方程的文档。
引用
插入任何内容工具还可用于在你的文档中插入引用。
在下一个窗口中，你可以通过多种来源插入引用，包括文档参考文献、Zotero个人或群组库、DOI（文档对象标识符）引用以及Crossref、DataCite或PubMed的搜索。你可以在这里了解更多关于可视化编辑器引用的信息。
在左侧选择从DOI，并将DOI 10.1093/comjnl/27.2.97复制粘贴到搜索栏中并点击搜索。然后，选择找到的参考文献，并将其插入到你的文档中。
如果这是你第一次向文档添加引用，RStudio会自动为你创建一个参考文献文件。该文件默认命名为references.bib，RStudio还会在你的文档YAML元数据中添加bibliography: references.bib。
请注意，参考文献中的条目使用@citeid语法引用。将以下文本添加到你的文档中。
我们将使用literate programming进行此分析 [@knuth1984]。参考文献将包含在文档末尾，因此我们在笔记本底部添加一个## 参考文献标题。你还可以通过点击三个点（…）来编辑其属性，为该部分添加.unnumbered类。
以下是文档渲染后的样子（为了突出相关部分，中间部分已删除）。
@引用语法非常灵活，支持前缀、后缀、定位符和行内引用。了解更多信息，请参阅引用的文档。
交叉引用
交叉引用通过提供编号引用和超链接到图表、表格、方程和章节，使读者更容易导航你的文档。通常，可交叉引用的实体需要一个标签（唯一标识符）和一个标题。
例如，要为之前插入的方程添加标签，请点击三个点以编辑其属性，并使用建议的格式（以#eq-开头）为方程添加标签。
然后，在可视化编辑器中使用插入任何内容工具添加交叉引用。你可以添加一个句子如"我们可以拟合一个形式如"来为交叉引用提供上下文，然后在句末添加引用。
在插入交叉引用菜单中，导航到左侧所需交叉引用实体，并选择之前标记的方程。 
或者，在可视化编辑器中开始输入要引用的方程的标签，自动填充工具将会弹出可供选择的交叉引用。
以下我们通过您正在处理的文档中的片段来说明如何交叉引用各种类型的实体。
我们在@sec-eda中展示了探索性数据分析的结果，并在@sec-model中展示了回归模型。
@fig-scatterplot以散点图显示了这两个变量之间的关系。
@tbl-stats显示了这两个变量的基本汇总统计数据。
我们可以拟合一个形式如@eq-slr所示的简单线性回归模型。这些例子包括交叉引用的章节、图表和方程。下表总结了我们如何表达这些引用。
| 实体 | 引用 | 标签 / 标题 |
|---|---|---|
| 章节 | @sec-eda |
添加到标题的ID: | |
| 图表 | @fig-scatterplot |
代码单元格中的YAML选项: | |
| 表格 | @tbl-stats |
代码单元格中的YAML选项: | |
| 方程 | @eq-slr |
显示方程的末尾: | |
请参阅关于交叉引用的文章以了解更多信息，包括如何自定义标题和引用文本（例如使用“图”而不是“图表”）。
注释
注释是吸引额外注意力到某些概念的绝佳方式，或者更清楚地表明某些内容是补充性的或仅适用于某些场景。
注释是具有特殊注释属性的markdown div。我们可以使用Insert Anything工具插入注释。 
在随后的对话框中，你可以选择五种标注类型之一（注释、提示、重要、警告或危险），自定义其外观（默认、简单或最小化），并决定是否显示图标。
然后，尝试在标注框中插入以下文本。
这是一个相当不完整的分析，但希望该文档能提供一些关于 Quarto 创作功能的好概述！以下是在可视化编辑器中的标注外观。
以下是输出文档中渲染的标注外观。
你可以在标注文档中了解更多关于不同类型的标注及其外观选项的信息。
文章布局
Quarto 文章的主体默认宽度约为 700 像素。 此宽度选择是为了优化可读性。 这通常会在文档边距中留下一些可用空间，有几种方法可以利用这些空间。
我们可以使用 column: page-right 单元格选项来指示我们希望图表占据屏幕的全宽，并带有一定的内边距。 继续为标记为 fig-histogram 的代码块添加此选项。
#| label: fig-histogram
#| fig-cap: "个体变量的直方图"
#| fig-subcap:
#| - "价格直方图"
#| - "面积直方图"
#| layout-ncol: 2
#| column: page-right以下是渲染文档的相关部分外观。
你可以在边距中定位引用、脚注和边注。 你还可以为图表、表格或其他内容定义自定义列跨度。 有关更多详细信息，请参阅文章布局文档。
发布
一旦你的文档渲染为 HTML，你可以通过点击编辑器工具栏或预览窗口上的
发布按钮，简单地发布到 RPubs（RStudio 提供的一个用于在网络上分享文档的免费服务）。 或者，你可以使用 quarto::quarto_publish_doc() 函数。
quarto::quarto_publish_doc(
"authoring.qmd",
server = "rpubs.com"
)其他可能的发布选项包括 RStudio Connect 和 ShinyApps 以及 GitHub Pages、Netlify 等。 发布 HTML 文章提供了关于你的发布选项的更详细概述。
如果你按照本教程的步骤一步步操作，你现在应该有一个实现了我们所涵盖内容的 Quarto 文档。 否则，你可以下载完成版的 computations.qmd 如下。
进一步学习
你现在已掌握了使用 Quarto 的基础知识！一旦你感到在创建和自定义文档方面得心应手，以下是一些值得探索的进阶内容：