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