Citations for 'Knitr' Markdown Files

Provides the ability to create dynamic citations in which the bibliographic information is pulled from the web rather than having to be entered into a local database such as 'bibtex' ahead of time. The package is primarily aimed at authoring in the R 'markdown' format, and can provide outputs for web-based authoring such as linked text for inline citations. Cite using a 'DOI', URL, or 'bibtex' file key. See the package URL for details.

title: An introduction to knitcitations author: Carl Boettiger date: 27 May 2014 bibliography: references.bib

Build Status Project Status: Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows. CRAN_Status_Badge

knitcitations is an R package designed to add dynamic citations to dynamic documents created with Yihui's knitr package.


Install the development version directly from Github


Or install the current release from your CRAN mirror with install.packages("knitcitations").

Quick start: rmarkdown (pandoc) mode

Start by loading the library. It is usually good to also clear the bibliographic environment after loading the library, in case any citations are already stored there:


Set pandoc as the default format:

options("citation_format" = "pandoc")

(Note: The old method will eventually be depricated. For documents using knitcitations <= 0.5 it will become necessary to set this as "compatibility").

Cite an article by DOI and the full citation information is gathered automatically. By default this now generates a citation in pandoc-flavored-markdown format. We use the inline command citep("10.1890/11-0011.1") to create this citation [@Abrams_2012].

An in-text citation is generated with citet, such as citet("10.1098/rspb.2013.1372") creating the citation to @Boettiger_2013.

Cite by URL

Not all the literature we may wish to cite includes DOIs, such as arXiv preprints, Wikipedia pages, or other academic blogs. Even when a DOI is present it is not always trivial to locate. With version 0.4-0, knitcitations can produce citations given any URL using the Greycite API. For instance, we can use the call citep("") to generate the citation to the Greycite tool [@greycite2739].

Cite bibtex and bibentry objects directly

We can also use bibentry objects such as R provides for citing packages (using R's citation() function): citep(citation("knitr") produces [@Xie_2014; @Xie_2013; @Xie_2014a]. Note that this package includes citations to three objects, and pandoc correctly avoids duplicating the author names. In pandoc mode, we can still use traditional pandoc-markdown citations like @Boettiger2013 which will render as @Boettiger2013 without any R code, provided the citation is already in the .bib file we name (see below).

Re-using Keys

When the citation is called, a key in the format FirstAuthorsLastName_Year is automatically created for this citation, so we can now continue to cite this article without remembering the DOI, using the command citep("Abrams_2012") creates the citation [@Abrams_2012] without mistaking it for a new article.

Displaying the final bibliography

At the end of the document, include a chunk containing the command:


Use the chunk options echo=FALSE and message=FALSE to hide the chunk command and output.

This creates a Bibtex file with the name given. Pandoc can then be used to compile the markdown into HTML, MS Word, LaTeX, PDF, or many other formats, each with the desired journal styling. Pandoc is now integrated with RStudio through the rmarkdown package. Pandoc appends these references to the end of the markdown document automatically. In this example, we have added a yaml header to our Rmd file which indicates the name of the bib file being used, and the optional link to a CSL stylesheet which formats the output for the ESA journals:

bibliography: "references.bib"
csl: "ecology.csl"

Then calling rmarkdown::render("tutorial.Rmd") from R on the tutorial compiles the output markdown, with references in the format of the ESA journals.




For more fine-grained list of changes or to report a bug, consult


Releases will be numbered with the following semantic versioning format:


And constructed with the following guidelines:

  • Breaking backward compatibility bumps the major (and resets the minor and patch)
  • New additions without breaking backward compatibility bumps the minor (and resets the patch)
  • Bug fixes and misc changes bumps the patch
  • Following the RStudio convention, a .99 is appended after the patch number to indicate the development version on Github. Any version Coming from Github will now use the .99 extension, which will never appear in a version number for the package on CRAN.

For more information on SemVer, please visit



  • Avoid example that depends on XML (no longer inherited dependency from RefManageR)
  • add badges to README


  • Avoid failures in CRAN tests do to network connectivity issues.
  • Update importFrom directive for previously-considered-base package, utils


  • Add template file for the MIT license, as requested from CRAN. We include the entire MIT License


  • Add error handling when Greycite API cannot be reached


  • Update vignette to reflect changes to rmarkdown and pandoc (see #67)
  • Fixed missing citation in vignette building (knitcitations default format for bibtex keys now has an underscore, LastName_Year)


  • Fix passing of arguments to cite_options that was causing many options to be ignored. (See #63)
  • Added \donttest on examples needing internet connection (resource may not be available)
  • Licence migrated to MIT


This version is a ground-up rewrite of knitcitations, providing a more powerful interface while also streamlining the back end, mostly by relying more on external libraries for knitty gritty. While an effort has been made to preserve the most common uses, some lesser-used functions or function arguments have been significantly altered or removed. Bug reports greatly appreciated.

  • citet/citep now accept more options. In addition to the four previously supported options (DOI, URL, bibentry or bibkey (of a previously cited work)), these now accept a plain text query (used in a CrossRef Search), or a path to a PDF file (which attempts metadata extraction).

  • Citation key generation is now handled internally, and cannot be configured just by providing a named argument to citet/citep.

  • The cite function is replaced by bib_metadata. This function takes any argument to citet/citep as before (including the new arguments), see docs.

  • Linked inline citations now use the configuration: cite_options(style="markdown", hyperlink="to.doc") provides a link to the DOI or URL of the document, using markdown format.

  • Support for cito and tooltip have been removed. These may be restored at a later date. (The earlier implementation did not appropriately abstract the use of these features from the style/formatting of printing the citation, making generalization hard.

  • bibliography now includes CSL support directly for entries with a DOI using the style= argument. No need to provide a CSL file itself, just the name of the journal (or rather, the name of the corresponding csl file: full journal name, all lower case, spaces as dashes). See

  • bibliography formatting has otherwise been completely rewritten, and no longer uses print_markdown, print_html, and print_rdfa methods. rdfa is no longer available, and other formats are controlled through cite_options. For formal publication pandoc mode is recommended instead of bibliography.


  • Apply accents to names for in-text citations (issue #51)
  • Use first name if author last name is not available, e.g. citet(citation()) (issue #55)


  • Bugfix in default citep method (caused by missing page argument)


  • Pandoc formatting is introduced as the prefered way to handle citations. The .Rmd files remain as before, importing citation data on the fly with citep() and citet taking DOIs, URLs, or bibentries as arguments, but render in pandoc's markdown. The citations used are written to a bibtex file and the user must use pandoc (either directly or through RStudio's rmarkdown) to format the citations appropriately. See the updated vignette & README. This method has to be enabled with options(citation_format = "pandoc") at present, otherwise compatibility mode is enabled by default. (see #57)


  • html print method now provides support for bulleted lists, see #41


  • Hard-wrap roxygen documentation to avoid line overflows in pdf manual


  • html print method now handled directly in knitcitations just like the markdown print method, with ordering, etc, since default html printing method sucks
  • Tooltip provides HTML formatting, with link (issue #37)
  • HTML formatting inside tooltip (data-html="true") removed, since incompatible with Pandoc parser. pandoc/#831


  • Provide page range as option to citep and citet (see issue #32)
  • Fixes a bug in which page numbers were not grabbed from the DOI look-up
  • Date added to Description file so that users can cite the development version properly (#34)


  • Depends R (>= 2.15.0)
  • Released to CRAN (2013-03-18)
  • Minor changes: replace paste0 with paste, sep=""


  • Some bugfixes to bib_format method
  • tooltip javascript uses class 'showtooltip' rather than rel='tooltip' to avoid conflicting semantic meaning and styling and to avoid clashes with
    existing 'tooltip' class in twitter bootstrap
  • cito links fix href and use rel instead of property


  • Testing out bib_format method to change order of citation elements in reference list


  • Fixes Issue #27 in rdfa printing
  • Nicer markdown printing
  • keep each function in separate file


Major changes

  • Support for citations by URL. Paste the full URL of any academic journal or other webpage. Uses the Greycite API
  • Introduces linked inline citations as an option (previously active only for CITO links). Inline citation text will be linked directly to the article by DOI or URL. Toggle on or off using cite_options globally, or passing linked=FALSE to the calls to citet or citep
  • Introduces tooltips option. Mouse over an inline citation and see the full citation information. * Introduces cite_options, to toggle certain settings such as tooltips, linked inline text,

Minor changes

  • in-line link will use URL if a DOI is not found
  • cite is now exported to the namespace. Useful to return a bibentry object given a DOI or URL.


  • Fix formatting of parenthetical citations (bug introduced previously converted these to citet format)
  • Additional documentation
  • Install instructions for development version added to README


  • Avoid dropped citations caused by redundant key collisions, closes #21


  • Added a new display option, bibliography('markdown')
  • fixed BUG in the printing of the text-based name in bibliography for bibstyle-based calls


  • Semantic citations now enabled. bibliography can print with method 'rdfa' to provide RDFa enhanced HTML bibliography data, and citations can take cito arguments as an option. (Closes issues #16 and #17)
  • bibliography now takes more options to match the bibstyle and print.bibentry functions.
  • citet and citep take an optional argument for formating the citation, defaulting to authoryear format. Future versions may move this into an option.
  • newbib() function initializes and clears existing cache files.
  • updated with semantic examples and more background text (generated by inst/examples/README.Rmd).
  • Some basic unit tests built in. Could use more, but meanwhile closes #8.
  • Test cases work with knit2html button in RStudio, closes #14


  • Switched to handling citation data using environment rather than an external bibfile. This does not refer to the handling of user-provided bibtex files as input data, which are supported as before, but changes only the backend management of that data. The external bibtex file method can be switched back on by setting options("bibtex_data" = TRUE).
  • There is no need to call print(bibliography, "html"), one can simply call bibliography() or bibliography("html"). Sort is still an option, other options that were for internal use (debug, remove_duplicates) are removed as they are no longer necessary.
  • Several new functions have been added to handle the new methods.


  • Fix vignette error that prevents knitr 1.0 submission
  • Fixed errors on installing package and lack of entries in bibliography
  • Semantic print option added but still in early testing


  • bibliography() now takes style as an option (html, text, bibtex output)
  • imports write.bib from pkgmaker package instead of from doRNG
  • URL in description on CRAN


  • Initial Release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.0.12 by Carl Boettiger, a year ago

Report a bug at

Browse source code at

Authors: Carl Boettiger [aut, cre]

Documentation:   PDF Manual  

Task views: Reproducible Research

MIT + file LICENSE license

Imports RefManageR, digest, httr, methods, utils

Suggests testthat, knitr, rmarkdown

Imported by datelife.

Suggested by DeLorean, RNeXML, blin, netregR, wrswoR.

See at CRAN