Technical Writing

Visual mode includes extensive support for Quarto features frequently used in technical writing including equations, citations, cross-references, footnotes, embedded code, and LaTeX. This article describes using these features in more depth.

Equations

LaTeX equations are authored using standard Pandoc markdown syntax (the editor will automatically recognize the syntax and treat the equation as math). When you aren’t directly editing an equation it will appear as rendered math:

An RMarkdown document opened in the R Studio Visual Editor. The first section is titled 'Inline Math'. It displays two separate lines of text with inline mathematical text. The second section is titled 'Display Math'. It has a line containing two $ characters, a mathematical equation written in LaTeX below that, and a a line containing two $ characters below that. Underneath that is the rendered output of the mathematical equation.

As shown above, when you select an equation with the keyboard or mouse you can edit the equation’s LaTeX. A preview of the equation will be shown below it as you type.

Cross References

Cross References make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures, tables, and equations.

Every cross-referenceable entity requires a label (unique identifier) and caption (description). For example, this is a cross-referenceable figure:

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

The presence of the caption (“Elephant”) and label (#fig-elephant) make this figure referenceable. This enables you to use the following syntax to refer to it elsewhere in the document:

See @fig-elephant for an illustration.

Here is what this would look like rendered to HTML:

A line drawing of an elephant. The text 'Figure 1: Elephant' is centered beneath it. The text 'See fig. 1 for an illustration' is aligned to the left underneath that.

See the article on Cross References for full documentation on creating cross references and customizing their display.

Use the Insert -> Cross Reference… command to insert a cross reference:

The 'Insert Cross Reference' window in R Studio. There is a vertical section taking approximately a quarter of the window on the left with options for 'All Types', 'Sections', 'Figures', 'Tables', 'Equations', 'Listings', and 'Theorems'. Running along the top of the right side of the window is a search bar with the text 'fig-env' typed out. Underneath that is a large search results pane that takes up the rest of the window. Each of the search results has a title of the form '@fig-env*', an image icon to the left, the file name where the figure was found the far right side, and some of the surrounding text from where the reference was found underneath it.

You can also just type the prefix of a cross reference label (e.g. @fig-env) and select it via auto-complete:

A document opened in the R Studio Visual Editor. The text '@fig-env' is highlighted in blue and a pop-up window displaying search results is displayed underneath it. Each of the search results has a title of the form '@fig-env*', an image icon to the left, the file name where the figure was found the far right side, and some of the surrounding text from where the reference was found underneath it.

Similar to hyperlinks, you can also navigate to the location of a cross-reference by clicking the popup link that appears when it’s selected:

A document opened in the R Studio Visual Editor. The text '@fig-break-point' is highlighted in blue and a pop-up window displaying where that text links to is displayed beneath it. The pop-up window has 'fig-break-point' in blue, underlined text on top, the text 'Break points provide the graphical equivalent of a browser statement' in black text underneath that, and the file name 'a5-debug.qmd' in light gray text beneath that.

You can also navigate directly to any cross-reference using IDE global search:

The top part of an RStudio IDE window. The phrase 'fig-en' is typed into the search bar at the center top of the page and search results appear underneath it. Each of the search results has a title of the form 'fig-en*' in black, an image icon to the left, and the file location in parentheses and light gray text to the right.

Footnotes

You can include footnotes using the Insert -> Footnote command (or the ⇧⌘ F7 keyboard shortcut). Footnote editing occurs in a pane immediately below the main document:

A Markdown document containing three paragraphs opened in the R Studio visual editor. The sentence at the end of the paragraph has a superscript '1' at the end, indicating a footnote. This '1' is surrounded by a blue box. There is a section divider underneath the three paragraphs, under which is another paragraph labeled '1'.

By default footnotes will be written in markdown immediately below the block in which they appear. You can customize this behavior via editor options.

Embedded Code

Source code which you include in a Quarto document can either be for display only or can be executed by Jupyter or Knitr as part of rendering. Code can furthermore be either inline or block.

Displaying Code

To display but not execute code, either use the Insert -> Code Block menu item, or start a new line and type either:

  1. ``` (for a plain code block); or
  2. ```<lang> (where <lang> is a language) for a code block with syntax highlighting.

Then press the Enter key. To display code inline, simply surround text with backticks (`code`), or use the Format -> Code menu item.

Code Chunks

To insert an executable code chunk, use the Insert -> Code Chunk menu item, or start a new line and type:

```{r}

Then press the Enter key. Note that r could be another language supported by knitr (e.g., python or sql) and you can also include a chunk label and other chunk options.

To include inline R code, create normal inline code (e.g., by using backticks or the ⌘ D shortcut) but preface it with {r} (or r). For example, to include the current date using the R function Sys.Date() you would use: `{r} Sys.Date()`.

Note that when the code displays in visual mode it won’t have the backticks (but they will still appear in source mode).

Running Chunks

You can execute the currently selected R or Python code chunk using either the run button at the top right of the code chunk or using the ⇧⌘ Enter keyboard shortcut:

An R Markdown document opened in the R Studio Visual editor. There is some plain text, a code chunk with a gray background underneath that, and the plot resulting from executing that code underneath that. In the top right corner of the code chunk is a green arrow that is used for executing that code chunk.

You can execute code chunks up to the current one using the toolbar button or using the ⌥⌘ P keyboard shortcut.

LaTeX and HTML

You can also include raw LaTeX commands or HTML tags when authoring in visual mode. The raw markup will be automatically recognized and syntax highlighted. For example:

An R Markdown document opened in the R Studio visual editor. The first line reads: 'The implementation of the \pkg{shiny} package uses lots of 'proglang{JavaScript}. Both '\pkg' and '\proglang' are highlighted in pink, indicating that Visual Editor recognizes it as a LaTeX command. The second contains a <kbd> html tag highlighted in pink. Visual Editor recognizes this as an HTML tag and renders the results in the live document.

The above examples utilize inline LaTex and HTML. You can also include blocks of raw content using the commands on the Format -> Raw menu. For example, here is a document with a raw LaTeX block:

An R Markdown document opened in the R Studio visual editor. There is raw LaTeX describing a table surrounded by a pink rectangle. The rectangle runs the width of the page. At the top right of the pink rectangle is the label 'latex' and another button labeled by three dots. The

Note that Pandoc ignores LaTeX commands when not producing LaTeX based output, and ignores HTML tags when not producing HTML based output.

Citations

Visual mode uses the standard Pandoc markdown representation for citations (e.g. [@citation]). Citations can be inserted from a variety of sources:

  1. Your document bibliography.
  2. Zotero personal or group libraries.
  3. DOI (Document Object Identifier) references.
  4. Searches of Crossref, DataCite, or PubMed.

If you insert citations from Zotero, DOI look-up, or a search then they are automatically added to your document bibliography.

Bibliographies

Pandoc supports bibliographies in a wide variety of formats including BibTeX and CSL. Add a bibliography to your document using the bibliography YAML metadata field. For example:

---
title: "My Document"
bibliography: references.bib
link-citations: true
---

Note that we’ve also specified the link-citations option, which will make your citations hyperlinks to the corresponding bibliography entries.

See the Pandoc Citations documentation for additional information on bibliography formats.

Inserting Citations

You insert citations by either using the Insert -> Citation command or by using markdown syntax directly (e.g. [@cite] or @cite) .

Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of ‘@’ + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. The citation key must begin with a letter, digit, or _, and may contain alphanumerics, _, and internal punctuation characters (:.#$%&-+?<>~/). Here are some examples:

Blah Blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
Blah Blah [@doe99, pp. 33-35, 38-39 and passim].
Blah Blah [@smith04; @doe99].
Smith says blah [-@smith04].

You can also write in-text citations, as follows:

@smith04 says blah.
@smith04 [p. 33] says blah.

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:

---
title: "Reproducible Research"
zotero: "Reproducible Research Series (Year 1)"
---

Note that you can also turn off Zotero entirely for a document using zotero: false:

---
title: "Reproducible Research"
zotero: false
---

Zotero Web API

If you are using RStudio Server and/or don’t have Zotero installed locally, you can still access your Zotero library using the Zotero Web API (assuming you have a Zotero web account and have synced your libraries to your account).

If you are running RStudio Desktop, it’s generally easier to also run Zotero on your desktop and access your library locally. That said, it is possible to access Zotero web libraries from RStudio Desktop if you prefer that configuration.

API Access Key

RStudio accesses Zotero web libraries using the Zotero Web API, so the first step is to create a Zotero account and then configure Zotero to sync its data to your account. You can do this using the Sync tab of the Zotero preferences:

The Sync tab of Zotero preferences.

Once you’ve configured your library to sync, you need to create a Zotero API Key to use with RStudio:

The 'New Private Key' section of Zotero. The 'Allow library access' option is selected.

Follow the instructions to create a new access key. Note that if you want to use Group Libraries with RStudio that you should change the default to provide read-only access to groups (as illustrated above).

Be sure to record your key after generating it (i.e. copy it to the clipboard and/or save it somewhere more permanent) as you won’t be able to view it again after you navigate away.

Finally, go to the R Markdown -> Citations preferences to connect Zotero to RStudio using your key:

Set the Zotero Library option to “Web”, then paste in your Zotero Web API Key. You can use Verify Key… button to confirm that your Zotero API key is working correctly.

Once you’ve confirmed your connection you are ready to start inserting citations from Zotero.