Quarto 入门教程 (4)：添加内容，公式，引用

简介

本文是《手把手教你使用 Quarto 构建文档》第四期，前三期分别介绍了：

1. 第一期 介绍了Quarto 构建文档的原理；可创建的文档类型；对应的参考资源分享。
   
2. 第二期 介绍了如何使用 Quarto，并编译出文档（PDF，MS Word，html）等。
   
3. 第三期 介绍了 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）模式

1. 使用“ Insert Anything 插入任何内容^[5]”工具。在空位置的开头使用 / 或在其他任何地方使用 Cmd+/ 来访问它。

2. 使用手动按钮操作：

• 基于源代码（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