简介
本文是《手把手教你使用 Quarto 构建文档》第四期，前三期分别介绍了：
- 第一期 介绍了Quarto 构建文档的原理；可创建的文档类型；对应的参考资源分享。
- 第二期 介绍了如何使用 Quarto，并编译出文档（PDF，MS Word，html）等。
- 第三期 介绍了 Quarto 细节设置部分：代码框、图形、数据框、内联代码、缓存设置。
本期将介绍 Quarto 如何添加内容，公式，引用等组件，主要参考官网教程[1]。
多种格式输出
第二期 介绍了生成不同格式的文档，但只是说明输出单个格式。如果读者需要创建的某些文档需要多种输出格式。可以将其他格式添加到文档中，并修改针对每种格式的一些选项。例如：
--- 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 ---
其中，包括了 DOCX、HTML 和 PDF 为可选选项。在 HTML 格式中，设置了代码折叠，并使用 katex 呈现数学文本。PDF 中定义了页面边际。DOCX 中设置为 docx: default，即表示使用默认选项。
注意：YAML 中的缩进很严格，小心报错！
此时，编译后的界面如下所示
根据右边编译出的结果，手动选择不同版本，GIF 如下所示：
在该 qmd 的文件夹下可以找到对应的源文件。
章节设置
为了方便读者更轻松地浏览文档，你可以在 YAML 中使用 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[2], PDF[3], MS Word[4]。
公式
如果读者想将 LaTeX 方程添加到 RStudio 中的 Quarto 文档中。有以下几种方式：
- 基于可视化（visual）模式
- 使用“ Insert Anything 插入任何内容[5]”工具。在空位置的开头使用
/或在其他任何地方使用Cmd+/来访问它。
- 使用手动按钮操作：
- 基于源代码（Source）模式
如果想在新的一行展示公式，可以用$$…$$，内联方程式用 $…$。
例如：在新一行展示以下公式。
price = \hat{\beta}_0 + \hat{\beta}_1 \times area + \epsilon
此时界面会自动展示出渲染后的结果。
引用
如果读者想在文档中引用参考文献，网站等。可以使用前面所说的“插入任何内容”工具。
点击 Citation 后，会跳转到另一个窗口。您可以通过各种来源插入引文，包括文档书目、Zotero[6] 、DOI[7]（文档对象标识符）参考文献以及通过 Crossref[8]、DataCite[9]或 PubMed[10] 搜索得到的文献。读者可以在[此处]((https://quarto.org/docs/visual-editor/technical.html#citations "此处"))找到有关使用可视化编辑器引用的更多信息。
如果这是读者添加到文档中的第一个参考文献，RStudio 将自动为您创建一个参考书目文件。默认情况下，该文件名为 references.bib，RStudio 还会将 bibliography:：references.bib 自动添加到文档的 YAML 元数据中。
注意：参考书目中的项目使用
@Citeid语法引用。将以下文本添加到您的文档中。我想引用一篇参考文献：[@kang2022]，此时会得到以下结果：此外，参考文献将自动包含在文档末尾。
交叉引用
交叉引用通过提供数字、表格、方程和章节的编号参考和超链接，使读者能够更轻松地浏览文档。可交叉引用的实体通常需要标签（唯一标识符）和标题。
例如，要为之前插入的方程添加标签，请单击三个点来编辑其属性，并使用建议的格式（以 #eq- 开头）来标记方程。
然后，使用可视化编辑器中的“插入任何内容”工具添加交叉引用。可以添加诸如“我们可以拟合所示形式的简单线性回归模型”之类的句子来将交叉引用置于上下文中，然后将引用添加到该句子的末尾。
点击进入新的界面，选择需要交叉引用的标签。
同理，章节，图像，表格等的交叉引用也类似如此。详见交叉引用说明文档[11]。
文字标注
标注是引起某些概念的额外关注的绝佳方法，或者更清楚地表明某些内容仅适用于某些情况。
- 使用“插入任何内容”工具添加标注。
- 点击进入新的窗口，可以选择五种标注类型之一（注释、提示、重要、注意或警告），自定义其外观（默认、简单或最小），并决定是否要显示图标。
假设我们加入以下文字到标注框中：
这是庄闪闪创建的 Quarto 入门教程。
此时，你可以看到以下界面：
编译后的结果如下：
读者可以在标注文档[12]中了解有关不同类型标注及其外观选项的更多信息。
文章排版
Quarto 文章正文的默认宽度约为 700 像素。这通常会在文档页边距中留下一些可用空间，读者可以通过多种方式利用该空间。
我们可以使用 column: page-right 选项来指示所需图形占据屏幕的整个宽度，并加入一些图形。例如，以下代码并排加入了两个图形。
#| 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
运行后得到的结果如下：
读者害可以在页边空白处放置引文、脚注等。还可以为图形、表格或其他内容定义自定义列跨度。有关更多详细信息，请参阅有关文章布局[13]文档。
发布
将文档渲染为 HTML 后，只需单击编辑器工具栏或预览窗口上的“发布”按钮即可将其发布到 RPubs[14]。
或者可以使用 quarto::quarto_publish_doc() 函数。
quarto::quarto_publish_doc( "authoring.qmd", server = "rpubs.com" )
其他可能的发布选项包括 RStudio Connect 和 ShinyApps 以及 GitHub Pages、Netlify 等。发布 HTML[15] 文章更详细地概述了发布选项。
参考资料
[1]
官网教程: https://quarto.org/docs/get-started/authoring/rstudio.html
[2]
HTML: https://quarto.org/docs/output-formats/html-basics.html
[3]
PDF: https://quarto.org/docs/output-formats/pdf-basics.html
[4]
MS Word: https://quarto.org/docs/output-formats/ms-word.html
[5]
Insert Anything 插入任何内容: https://quarto.org/docs/visual-editor/#insert-anything
[6]
Zotero: https://quarto.org/docs/visual-editor/technical.html#citations-from-zotero
[7]
DOI: https://quarto.org/docs/visual-editor/technical.html#citations-from-dois
[8]
Crossref: https://www.crossref.org/
[9]
DataCite: https://datacite.org/
[10]
PubMed: https://pubmed.ncbi.nlm.nih.gov/
[11]
交叉引用说明文档: https://quarto.org/docs/authoring/cross-references.html
[12]
标注文档: https://quarto.org/docs/authoring/callouts.html
[13]
文章布局: https://quarto.org/docs/authoring/article-layout.html
[14]
RPubs: https://rpubs.com/
[15]
发布 HTML: https://quarto.org/docs/output-formats/html-publishing.html
