All files for this post located here.

Introduction

Rmarkdown is great for writing PDF papers with citations and a bibliography (references). To do so requires installing LaTeX—a freely available program for high-quality typesetting that optimized for science and mathematics. Rmarkdown deploys LaTeX in the background, but can also explicitly handle LaTeX commands. LaTeX uses BibTeX for citations and to generate a bibliography.

First, install the following open-source programs:

  1. R (https://cran.r-project.org/)
  2. RStudio (https://www.rstudio.com/)
  3. LaTeX (includes BibTeX)

Second, create a Rmarkdown file; for example, see the source file for this document (rmarkdown-biblio.Rmd). Here is the YAML header for this document:

--- 
title: "Rmarkdown with a BibTeX bibliography"
subtitle: A primer for technical writers
author: "Tomás J. Aragón"
date: "`r Sys.Date()`"
documentclass: article
output: 
  pdf_document:
    toc: false
bibliography: references.bib
link-citations: yes
linkcolor: red
urlcolor: blue
csl: vancouver-brackets.csl
description: "Rmarkdown to write papers with citations and a bibliography."
---

Notice that the YAML header points to the bibliography BibTeX ASCII file (references.bib) and to the bibliography style XML file (vancouver-brackets.csl). We will be editing the .bib file but not the .csl file. Citationstyles.org is the home of the Citation Style Language (CSL), a popular open XML-based language to describe the formatting of citations and bibliographies.1 For this article I used the Vancouver style which is popular with biomedical journals. The general approach is to download all the CSL styles and put them into a source directory, and in the YAML header have the file path pointing to your favorite CSL style. However, for now, put these three files into the a single directory: rmarkdown-biblio.Rmd, references.bib, and vancouver-brackets.csl.

Table 1: BibTeX bibliography entry types and description

Entry type Description Required fields
Article Article in journal author, title, journal, year
InProceedings Article in proceedings author, title, booktitle, year
InCollection Article in collection author, title, booktitle, publisher, year
InBook Chapter or pages in a book author or editor, title, chapter and/or pages, publisher, year
Proceedings Conference proceedings title, year
Book Book author or editor, title, publisher, year
Booklet Booklet title
PhdThesis PhD thesis author, title, school, year
MastersThesis Master’s thesis author, title, school, year
TechReport Technical report author, title, institution, year
Manual Technical manual title
Unpublished Unpublished author, title, note
Misc Miscellaneous none

Creating bibliographies

Study the accompanying BibTeX file (references.bib) which has three entries. Work with these. Later you can add more entry types which are listed in Table 1 with their required fields. Optional fields are also available.2 In truth, you have more optional fields than are officially listed. For example, I added the url field in the third record of references.bib (displayed below).

@Article{tja2017article,
  author = 	 {Tomas J. Aragon and Wayne T. Enanoria},
  title = 	 {Best article ever published!},
  journal = 	 {N Engl J Med},
  year = 	 {2017},
}

@Book{tja2017book,
  author = 	 {Tomas J. Aragon},
  editor = 	 {Wayne T. Enanoria},
  title = 	 {Best book ever published!},
  publisher = 	 {N Engl J Med},
  year = 	 {2017},
}

@Misc{tja2017misc,
  author = 	 {Tomas J. Aragon},
  title = 	 {Population Health Data Science},
  howpublished = {Online},
  month = 	 {10},
  year = 	 {2017},
  url = {https://taragonmd.github.io/datsci/}
}

Inserting citations

I am inserting an article citation here [1]. I am inserting an book citation here [2]. I am inserting an misc citation here [3]. And, I am inserting multiple citations here [1–3].

Here is the Rmarkdown that produced the preceding paragraph:

I am inserting an `article` citation here [@tja2017_article].  I am
inserting an `book` citation here [@tja2017_book].  I am inserting an
`misc` citation here [@tja2017_misc].  And, I am inserting multiple
citations here [@tja2017_article; @tja2017_book; @tja2017_misc].

Notice that I used a unique BibTeX key (e.g., @tja2017_article) to insert a citation. Each record in the .bib file must have a unique key. Finally, at the very end of the .Rmd file put the following section markdown:

# References

The references will be inserted after this section heading (see below).

Compiling article with citations and references

Again, put files (rmarkdown-biblio.Rmd, references.bib, and vancouver-brackets.csl) into the same directory and knit Rmd file using Rstudio.

Alternatively, you can compile from the console.

> rmarkdown::render('rmarkdown-biblio.Rmd')
...
...
Output created: rmarkdown-biblio.pdf

JabRef for managing bibliographies

A much better way to manage your BibTeX bibliography file (references.bib) is with JabRef.3 JabRef is an open source, professional quality bibliography reference manager. You cannot beat it! Enjoy!

Summary

Rmarkdown is how I write technical papers with citations and a bibliography. You only need three files (.Rmd, .bib, and .csl), RStudio, and LaTeX. Better yet, add JabRef to manage your bibliography (.bib) files.

References

  1. Aragon TJ, Enanoria WT. Best article ever published! N Engl J Med. 2017;
  2. Aragon TJ. Best book ever published! Enanoria WT, editor. Oxford University Press; 2017.
  3. Aragon TJ. Population health data science [Internet]. Online; 2017. Available from: https://taragonmd.github.io/datsci/