2.8 Citations

Pandoc offers two methods for managing citations and bibliographic references in a document.

  1. The default method is to use a Pandoc helper program called pandoc-citeproc, which follows the specifications of the Citation Style Language (CSL) and obtains specific formatting instructions from one of the huge number of available CSL style files.

  2. Users may also choose to use either natbib (based on bibtex) or biblatex as a “citation package”. In this case, the bibliographic data files need to be in the bibtex or biblatex format, and the document output format is limited to PDF. Again, various bibliographic styles are available (please consult the documentation of these packages).

    To use natbib or biblatex to process references, you can set the citation_package option of the R Markdown output format, e.g.,

    output:
  pdf_document:
    citation_package: natbib
  bookdown::pdf_book:
    citation_package: biblatex

Even if you choose natbib or biblatex for PDF output, all other output formats will be using pandoc-citeproc. If you use matching styles (e.g., biblio-style: apa for biblatex along with csl: apa.csl for pandoc-citeproc), output to PDF and to non-PDF formats will be very similar, though not necessarily identical.

For any non-PDF output format, pandoc-citeproc is the only available option. If consistency across PDF and non-PDF output formats is important, use pandoc-citeproc throughout.

The bibliographic data can be in several formats. We have only shown examples of BibTeX databases in this section, and please see the “Citations” section of the Pandoc manual for other possible formats.

A BibTeX database is a plain-text file (with the conventional filename extension .bib) that consists of bibliography entries like this:

@Manual{R-base,
  title = {R: A Language and Environment for Statistical
    Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2016},
  url = {https://www.R-project.org/},
}

A bibliography entry starts with @type{, where type may be article, book, manual, and so on.7 Then there is a citation key, like R-base in the above example. To cite an entry, use @key or [@key] (the latter puts the citation in braces), e.g., @R-base is rendered as R Core Team (2020), and [@R-base] generates “(R Core Team 2020)”. If you are familiar with the natbib package in LaTeX, @key is basically \citet{key}, and [@key] is equivalent to \citep{key}.

There are a number of fields in a bibliography entry, such as title, author, and year, etc. You may see https://en.wikipedia.org/wiki/BibTeX for possible types of entries and fields in BibTeX.

There is a helper function write_bib() in knitr to generate BibTeX entries automatically for R packages, e.g.,

# the second argument can be a .bib file
knitr::write_bib(c('knitr', 'stringr'), '', width = 60)
@Manual{R-knitr,
  title = {knitr: A General-Purpose Package for Dynamic
    Report Generation in R},
  author = {Yihui Xie},
  year = {2020},
  note = {R package version 1.30},
  url = {https://yihui.org/knitr/},
}

@Manual{R-stringr,
  title = {stringr: Simple, Consistent Wrappers for Common
    String Operations},
  author = {Hadley Wickham},
  year = {2019},
  note = {R package version 1.4.0},
  url = {https://CRAN.R-project.org/package=stringr},
}

@Book{knitr2015,
  title = {Dynamic Documents with {R} and knitr},
  author = {Yihui Xie},
  publisher = {Chapman and Hall/CRC},
  address = {Boca Raton, Florida},
  year = {2015},
  edition = {2nd},
  note = {ISBN 978-1498716963},
  url = {https://yihui.org/knitr/},
}

@InCollection{knitr2014,
  booktitle = {Implementing Reproducible Computational
    Research},
  editor = {Victoria Stodden and Friedrich Leisch and Roger
    D. Peng},
  title = {knitr: A Comprehensive Tool for Reproducible
    Research in {R}},
  author = {Yihui Xie},
  publisher = {Chapman and Hall/CRC},
  year = {2014},
  note = {ISBN 978-1466561595},
  url = {http://www.crcpress.com/product/isbn/
    9781466561595},
}

Once you have one or multiple .bib files, you may use the field bibliography in the YAML metadata of your first R Markdown document (which is typically index.Rmd), and you can also specify the bibliography style via biblio-style (this only applies to PDF output), e.g.,

---
bibliography: ["one.bib", "another.bib", "yet-another.bib"]
biblio-style: "apalike"
link-citations: true
---

The field link-citations can be used to add internal links from the citation text of the author-year style to the bibliography entry in the HTML output.

When the output format is LaTeX, the list of references will be automatically put in a chapter or section at the end of the document. For non-LaTeX output, you can add an empty chapter as the last chapter of your book. For example, if your last chapter is the Rmd file 06-references.Rmd, its content can be an inline R expression:

`r if (knitr::is_html_output()) '# References {-}'`

For more detailed instructions and further examples on how to use citations, please see the “Citations” section of the Pandoc manual.

References

R Core Team. 2020. R: A Language and Environment for Statistical Computing. Vienna, Austria: R Foundation for Statistical Computing. https://www.R-project.org/.

  1. The type name is case-insensitive, so it does not matter if it is manual, Manual, or MANUAL.↩︎