Enter VME mode

With the advent of RStudio version 1.4+, working with bibliographies and citing documents in R Markdown has much improved. In this tutorial we focus on best practices to further ease the citation experience when working with R Markdown documents. We also give some guidelines specific to the Research Institute for Nature and Forest.

More general tutorials can be found at the following web pages:

• https://pandoc.org/MANUAL.html#citations
• https://rstudio.github.io/visual-markdown-editing/citations.html

The latter webpage is part of the documentation about the Visual Markdown Editing (VME) mode that is available since RStudio 1.4+ as an alternative to writing R Markdown documents in source mode. VME is a what-you-see-is-what-you-get¹ interface for interacting with R Markdown. This interface is similar to writing documents in word processing software (google docs, MS Word, …). Moreover, the VME mode has more functionalities for citations than the source mode. To switch between source mode and VME, press the button :

In this tutorial, we assume you are familiar with the basics of R Markdown or Bookdown.

Preparing your R Markdown document to work with citations

There are various places where you can specify things that impact working with citations. The most important are specifications you can provide in the YAML header of your R Markdown document. Next to that, the RStudio global and project options provide some additional settings.

Document level specifications (YAML header specifications)

Specifying a bibliography

You can specify one or more bibliography files with the bibliography argument in a number of formats, including the most commonly used formats at the Research Institute for Nature and Forest: CSL-JSON, CSL-YAML, BibTex and EndNote.

We strongly recommend however to use CSL-JSON or CSL-YAML, since CSL is the native format for Pandoc.² All other bibliographic formats are internally converted to CSL-JSON, but with the exception of CSL-YAML this can in general not be perfect. Compared to CSL-JSON, Pandoc’s CSL-YAML has identical contents while having the most human-friendly syntax. CSL-JSON is the formal standard supported by all CSL processors³ .

Some example specifications:

---
author: Research Institute for Nature and Forest
date: '`r format(Sys.Date())`'
bibliography: references.yaml
---

Note that it is not even necessary at this stage that the bibliography file exists. It is possible to just give it a name and start adding citations in VME mode. When the first citation is inserted, for instance from a linked Zotero database, the file will be automatically created and the reference will be added to the file.

For users of Endnote, we recommend to export selected references to BibTeX format (as far as we know, it is not possible to export to CSL-JSON format). To do this:

• Edit -> Output Styles -> Open style manager and check the BibTex Export entry
• make sure that BibTex Export is checked in the Edit -> Output styles menu as well
• File -> Export, select Text file from the file type dropdown menu and save the file as <filename>.bibtex

We recommend to only include references in the bibliography file that are cited in the document.

---
author: Research Institute for Nature and Forest
date: '`r format(Sys.Date())`'
bibliography:
- path/to/my/ref.json
- other_references_from_endnote.bibtex
---

Specifying a citation style

The Research Institute for Nature and Forest has its own citation style. There is a separate tutorial that shows how to use this style in various reference manager software.

Specifying a citation style is done in the YAML header using the csl argument. The csl argument should be a path or URL to a CSL style file. To specify the style file for the Research Institute for Nature and Forest it is best to use the URL of the most up to date version:

---
author: Research Institute for Nature and Forest
date: '`r format(Sys.Date())`'
bibliography: ref.json
csl: https://raw.githubusercontent.com/citation-style-language/styles/master/research-institute-for-nature-and-forest.csl
---

Other YAML citation arguments

The ymlthis field guide, Pandoc & associated citeproc documentation and RStudio VME citations section mention the following useful arguments:

citation-abbreviations

Path to a CSL abbreviations JSON file, which can be used to translate from full journal titles to abbreviated journal titles. Examples of such files can be found here.

link-citations

Logical. Add citations hyperlinks to the corresponding bibliography entries? Default is false.

nocite

Citation IDs (@item1) to include in the bibliography even if they are not cited in the document. Including the wildcard pattern @* will include all citations in the bibliography regardless of whether they are cited in the document.

suppress-bibliography

Logical. Suppress bibliography? Default is false.

lang

Locale to use in formatting citations. If this is not set, the locale is taken from the default-locale attribute of the CSL file. en-US is used if a locale is not specified in either the metadata or the CSL file. The CSL style file of the Research Institute for Nature and Forest has been specifically checked and tailored for three different languages: lang: en, lang: nl and lang: fr.

reference-section-title

If this has a value, a section header with this title will be added before the bibliography. If reference-section-title is not specified and the document ends with a section header, this final header will be treated as the bibliography header.

zotero

Specify one or more Zotero libraries. Or false to turn of Zotero library entirely.

Here is an example of a valid YAML with all citation arguments:

---
author: Research Institute for Nature and Forest
date: '2022-02-02'
bibliography: ref.json
csl: https://raw.githubusercontent.com/citation-style-language/styles/master/research-institute-for-nature-and-forest.csl
citation-abbreviations: abbreviations.json
link-citations: true
nocite:
- '@item1'
- '@item2'
suppress-bibliography: false
lang: en-US
zotero: true
---

Rstudio project and global options

The project options allow you to select a Zotero reference manager library or libraries for the RStudio project you are working in. The default will detect your local Zotero library. It is also possible to point to other libraries, which can include a group library that is shared among co-workers.

The global options are more or less the same as the project options but will apply to all your RStudio projects. The defaults are OK.

Citing documents

Syntax

The following Markdown syntax is used to refer to documents. It is based on citation keys and the basic building block is @citationkey.

Insert a citation

You can either type the syntax in source mode, or use the insert citation button in VME mode. Using the VME mode has multiple benefits:

• autocompletion: typing @ will automatically show a list of available references

• searching and inserting references using one of the following methods (from the menu: Insert -> Citation; or shortcut CTRL+SHIFT+F8)

  • From the bibliography or bibliographies referred to in the YAML header’s bibliography field
  • From a Zotero library
  • From DOI
  • Crossref
  • DataCite
  • PubMed

This means that the Zotero reference manager is highly recommended when you want to work smoothly with citations in R Markdown. This reference manager also integrates nicely with other word processing software such as MS Word and Googledocs.

Citing R and R packages

The knitr::write_bib() function comes in handy if you need to cite R packages. The first argument accepts a character vector of R package names and the second argument can be used to specify a packages.bib file to which the BibTex entries will be written.

For instance:

# to cite specific packages
knitr::write_bib(c("base", "bookdown", "rmarkdown"), "packages.bib")

… allows us to cite @R-base, @R-bookdown and @R-rmarkdown if we add packages.bib to the bibliography YAML field.

Bibliography placement

By default, the bibliography will be placed at the end of the document. So, you will want a final header titled # References or # Bibliography at the end your document. See also the reference-section-title field that we discussed in Other YAML citation arguments.

If you want to place the bibliography somewhere else, for instance before the appendices, you can insert a div html tag in source mode:

# References

<div id="refs"></div>

# Appendix

If you use the bookdown::gitbook output format, further tweaks are possible. This format allows you to write a html report or book that consists of multiple html pages. You can for instance choose to split each chapter of a report into separate html pages. In that case, by default, the bibliography is split and all citation items that are cited on a given html page are put at the end of that page, so that readers do not have to navigate to a different bibliography page to see the details of citations. This feature can be disabled by setting the split_bib YAML field to FALSE, in which case all citations cited in the entire report or book are put on a separate bibliography page. To do this, you can add specific keys in the YAML header:

---
author: Research Institute for Nature and Forest
date: '`r format(Sys.Date())`'
site: bookdown::bookdown_site
output:
  bookdown::gitbook:
    split_by: chapter
    split_bib: false
---

References