可重复性研究

可视化模式包括对Quarto功能（常用于技术写作）的广泛支持，包括方程、引用、交叉引用、脚注、嵌入代码和LaTeX。本文将更深入地介绍如何使用这些功能。

方程

LaTeX方程使用标准的Pandoc Markdown语法编写（编辑器将自动识别语法并将方程视为数学内容）。当你不直接编辑方程时，它会以渲染的数学形式显示：

在R Studio可视化编辑器中打开的RMarkdown文档。第一部分标题为'内联数学'。它显示了两行单独的文本，带有内联数学文本。第二部分标题为'显示数学'。它有一行包含两个$符号，下面是使用LaTeX编写的数学方程，再下面是一行包含两个$符号。在这下面是数学方程的渲染输出。

如上所示，当你使用键盘或鼠标选择一个方程时，你可以编辑方程的LaTeX。当你输入时，方程的预览将显示在它下面。

交叉引用

交叉引用通过提供对各种实体（如图表、表格和方程）的编号引用和超链接，使读者更容易导航你的文档。

每个可交叉引用的实体都需要一个标签（唯一标识符）和标题（描述）。例如，这是一个可交叉引用的图表：

![大象](elephant.png){#fig-elephant}

标题(“大象”)和标签(#fig-elephant)的存在使得这个图表可以被引用。这使你可以在文档的其他地方使用以下语法引用它：

请参见@fig-elephant以查看示意图。

这是渲染为HTML时的样子：

一幅大象的线条画。下方居中显示文字'图1: 大象'。下方左对齐显示文字'请参见图1以查看示意图'。

有关创建交叉引用和自定义其显示的完整文档，请参见交叉引用文章。

使用插入 -> 交叉引用…命令插入交叉引用：

R Studio中的'插入交叉引用'窗口。左侧有一个垂直部分，占窗口大约四分之一，选项包括'所有类型'、'章节'、'图表'、'表格'、'方程'、'列表'和'定理'。右侧窗口顶部是一个搜索栏，输入了'fig-env'。下面是一个大的搜索结果窗格，占据了窗口的其余部分。每个搜索结果都有一个形如'@fig-env*'的标题、左侧的图像图标、右侧的文件名以及一些找到引用位置的周围文本。

你也可以只输入交叉引用标签的前缀（例如@fig-env）并通过自动补全选择它：

在R Studio可视化编辑器中打开的文档。文本'@fig-env'以蓝色高亮显示，并在其下方显示一个弹出窗口，显示搜索结果。每个搜索结果都有一个形如'@fig-env*'的标题、左侧的图像图标、右侧的文件名以及一些找到引用位置的周围文本。

类似于超链接，你也可以通过点击选中时的弹出链接导航到交叉引用的位置：

在R Studio可视化编辑器中打开的文档。文本'@fig-break-point'以蓝色高亮显示，并在其下方显示一个弹出窗口，显示该文本链接到的位置。弹出窗口顶部是蓝色、下划线的文本'fig-break-point'，下面是黑色文本'断点提供了浏览器声明的图形等价物'，再下面是浅灰色文本的文件名'a5-debug.qmd'。

你还可以使用IDE全局搜索直接导航到任何交叉引用：

RStudio IDE窗口的顶部部分。搜索栏位于页面中心顶部，输入了'fig-en'，搜索结果显示在其下方。每个搜索结果都有一个黑色标题'fig-en*'、左侧的图像图标，以及右侧括号中的文件位置和浅灰色文本。 ## 脚注 {#footnotes}

你可以使用插入 -> 脚注命令（或使用⇧⌘ F7快捷键）来包含脚注。脚注编辑在主文档正下方的面板中进行：

在R Studio可视化编辑器中打开的包含三个段落的Markdown文档。段落末尾的句子有一个上标'1'，表示这是一个脚注。这个'1'被一个蓝色框包围。在三个段落下方有一个分节符，分节符下方有一个标记为'1'的段落。

默认情况下，脚注会立即出现在其所在块的下方，并以Markdown格式书写。你可以通过编辑器选项自定义此行为。

嵌入代码

你在Quarto文档中包含的源代码可以仅用于显示，也可以由Jupyter或Knitr在渲染过程中执行。此外，代码可以是内联的，也可以是块形式的。

显示代码

要显示但不执行代码，可以使用插入 -> 代码块菜单项，或开始新的一行并输入：

  1. ```（用于普通代码块）；或
  2. ```<lang>（其中<lang>是某种语言）用于带有语法高亮的代码块。

然后按Enter键。要内联显示代码，只需用反引号包围文本（`code`），或使用格式 -> 代码菜单项。

代码块

要插入可执行的代码块，请使用插入 -> 代码块菜单项，或开始新的一行并输入： ```{r}

然后按下Enter键。请注意，r可以是knitr支持的其他语言（例如python或sql），您还可以包含块标签和其他块选项。

要包含内联R代码，只需创建正常的内联代码（例如，通过使用反引号或⌘ D快捷方式），但需在其前面加上r或{r}。例如，此内联代码将由knitr执行：`r Sys.Date()`。请注意，当在可视模式下显示代码时，它不会带有反引号（但在源代码模式下它们仍会显示）。

运行代码块

您可以使用代码块右上角的运行按钮或使用⇧⌘ Enter键盘快捷方式来执行当前选定的R或Python代码块：

在R Studio可视化编辑器中打开的R Markdown文档。有一些纯文本，下面是一个带有灰色背景的代码块，再下面是执行该代码生成的图。代码块的右上角有一个绿色的箭头，用于执行该代码块。

您可以使用工具栏按钮或使用⌥⌘ P键盘快捷方式来执行到当前代码块的所有代码块。

LaTeX和HTML

在可视化模式下编写时，您还可以包含原始LaTeX命令或HTML标签。原始标记将被自动识别并进行语法高亮。例如：

在R Studio可视化编辑器中打开的R Markdown文档。第一行内容为：'\pkg{shiny}包的实现使用了大量的proglang{JavaScript}。' 其中'\pkg'和'\proglang'以粉色高亮显示，表示可视化编辑器将其识别为LaTeX命令。第二行包含一个以粉色高亮的<kbd> html标签。可视化编辑器将其识别为HTML标签，并在实时文档中呈现结果。

上述示例使用了内联LaTeX和HTML。您还可以使用格式 -> 原始菜单中的命令来包含原始内容的块。例如，这里是一个带有原始LaTeX块的文档：

在R Studio可视化编辑器中打开的R Markdown文档。有一个描述表格的原始LaTeX块，周围有一个粉红色的矩形。矩形贯穿页面宽度。在粉红色矩形的右上角有一个标签'latex'和另一个由三个点标记的按钮。

请注意，当不生成基于LaTeX的输出时，Pandoc会忽略LaTeX命令，当不生成基于HTML的输出时，它会忽略HTML标签。

引用

可视化模式使用标准的Pandoc markdown表示法来引用（例如[@citation]）。引用可以从多种来源插入：

  1. 您的文档参考文献。
  2. Zotero个人或群组库。
  3. DOI（文档对象标识符）引用。
  4. Crossref、DataCite或PubMed的搜索。

如果您从Zotero、DOI查找或搜索中插入引用，它们会自动添加到您的文档参考文献中。

参考文献

Pandoc支持多种格式的参考文献，包括BibTeX和CSL。使用bibliography YAML元数据字段将参考文献添加到您的文档中。例如：

```markdown
---
title: "我的文档"
bibliography: references.bib
link-citations: true
---

请注意，我们还指定了 link-citations 选项，这将使您的引用成为指向相应参考文献条目的超链接。

有关参考文献格式的更多信息，请参阅 Pandoc 引用 文档。

插入引用

您可以通过使用 插入 -> 引用 命令或直接使用 Markdown 语法（例如 [@cite] 或 @cite）来插入引用。

引用放在方括号内，并用分号分隔。每个引用必须有一个键，由 @ + 数据库中的引用标识符组成，并且可以选择性地有一个前缀、定位符和后缀。引用键必须以字母、数字或 _ 开头，并且可以包含字母数字、_ 和内部标点字符（:.#$%&-+?<>~/）。以下是一些示例：

废话废话 [参见 @doe99，第33-35页；另见 @smith04，第1章]。
废话废话 [@doe99，第33-35页，38-39页及passim]。
废话废话 [@smith04; @doe99]。
史密斯说废话 [-@smith04]。

您也可以编写文内引用，如下所示：

@smith04 说废话。
@smith04 [第33页] 说废话。

See the Pandoc Citations documentation for additional information on citation syntax.

Use the toolbar button or the ⇧⌘ F8 keyboard shortcut to show the Insert Citation dialog:

The 'Insert Citation' window in RStudio. There is a vertical section that takes approximately a quarter of the window along the left side. Arranged vertically in this section are options for 'My Sources', 'Bibliography', 'Zotero', 'My Library', 'From DOI', 'Crossref', 'DataCite', and 'PubMed'. Along the top of the section on the right is a search bar. There is a black cursor over the words 'Search for citation' in light gray text. Underneath this search bar is a search results pane. Each of the search results has a title of the form '@citation-ref', an icon to the left, the title of the paper in light gray text underneath running along the length of the search result, and the citation in light gray text to the right. Running along the bottom of the window across both the left and right sections is a box with light gray text that says 'Select Citation Keys'. Underneath this and in the bottom left corner of the window is the text 'Add to bibliography' followed by a drop-down menu that currently has the value 'references.bib.' To the right of that is a button for the 'Use in-text citation' button. Finally, there are 'Insert' and 'Cancel' buttons arranged side-by-side.

Note that you can insert multiple citations by using the add button on the right side of the item display.

Markdown Syntax

You can also insert citations directly using markdown syntax (e.g. [@cite]). When you do this a completion interface is provided for searching available citations:

An R Markdown document opened in the R Studio Visual Editor. There is a cursor on at the end of the text '@R-htm', which is in brackets and comes after the text 'htmltools'. There is a dropdown menu underneath this text with search results that all begin '@R-htm'. Each of the search results has a title of the form '@R-htm' in bold, an icon to the left, the title of the cited reference underneath it in gray, and the citation in gray to the right.

Citation IDs

Before inserting a citation from an external source you may wish to customize its ID. Within the Insert Citation dialog, click the edit button on the right side of citations to change their ID:

The bottom section of the 'Insert Citation' menu in R Studio. There are two citations currently selected in the 'Selected Citations' section. Each of them are surrounded by a rectangle with rounded corners, and there is an 'x' button to the left of each of them. The first citation is currently selected and there is a cursor in citation ID, indicating that you are able to edit the ID.

If you insert a new citation via code completion, you will also be provided with the opportunity to change its default citation ID.

For citations inserted from Zotero, you can also use the Better BibTeX plugin to generate citation IDs (this can be enabled via Citation Options if you have Better BibTeX installed).

Citation Preview

Once you’ve inserted a citation, place the cursor over it to see a preview of it along with a link to the source if one is available:

An R Markdown document opened in the R Studio Visual Editor. The citation '@fayad2020' is surrounded in brackets. A citation preview that appears as a result of mousing over this citation is displayed. This preview includes a full citation in MLA format of the '@fayad2020' citation.

Citations from DOIs

Use the From DOI pane of the Insert Citation dialog to insert a citation based on a DOI (e.g. that you have retrieved from a PubMed or other search):

The 'Insert Citation' window in RStudio. The 'From DOI' option is selected in the left hand section. There is a DOI in the search bar that runs along the top of the section on the right, and the document corresponding to that DOI appears in the search results underneath. The search result has the title of the paper in black, the year published and journal in gray underneath that, the authors in gray underneath that, and the hyperlinked DOI underneath that. To the left of the title is a journal paper icon.

If you are using markdown syntax, you can also paste a DOI after the [@ and it will be looked up:

An R Markdown document opened in the R Studio Visual Editor. There is a DOI in blue text surrounded by brackets in the text. There is a pop-up window over the document titled 'Citation from DOI:' followed by the same DOI.' There is a text box titled 'Citation Id' containing a suggested citation ID that has been highlighted. Underneath that is a text box with citation information. From top to bottom, the information contained is: 'Title', 'Authors', 'Issue Date', 'Publication', 'Page(s)', 'Publisher', and 'DOI'. Underneath that are two more boxes arranged side-by-side. On the left is the 'Create bibliography file:' field with the text 'references.bib' filled in. To the right is the 'Format' drop down menu with 'BibLaTeX' currently selected.

Once you’ve confirmed that it’s the correct work (and possibly modified the suggested ID), the citation will be inserted into the document and an entry for the work added to your bibliography.

Citations from Zotero

Zotero is a popular free and open source reference manager. If you use Zotero, you can also insert citations directly from your Zotero libraries. If you have Zotero installed locally its location will be detected automatically and citations from your main library (My Library) will be available:

The 'Insert Citation' window in RStudio. The 'My Library' option is selected. The search bar at the top of the right section is empty, but the search results section is filled with the contents of a Zotero reference manager library. Each of the search result icons has a small 'Z' on the bottom right to indicate that the result comes from a Zotero library.

Zotero references will also show up automatically in completions:

Items from Zotero will appear alongside items from your bibliography with a small “Z” logo juxtaposed over them. If you insert a citation from Zotero that isn’t already in your bibliography then it will be automatically added to the bibliography.

If you are running both RStudio and Zotero on your desktop, then no additional configuration is required for connecting to your Zotero library. If however you using RStudio Server and/or want to access your Zotero library over the web, then a few more steps are required (see the Zotero Web API section for details).

Group Libraries

Zotero Groups provide a powerful way to share collections with a class or work closely with colleagues on a project. By default, Zotero Group Libraries are not included in the Insert Citation dialog or citation completions. However, there are options available to use group libraries at a global, per-project, or per-document level.

For example, here we specify a project-level option to use the Reproducible Research Series (Year 1) group library:

You can also specify one or more libraries within YAML. For example:

```

请注意，您也可以通过zotero: false完全关闭文档的Zotero功能：

``` yaml

title: “可重复性研究” zotero: false —