In knitcitations: Citations for 'Knitr' Markdown Files

knitcitations

• Author: Carl Boettiger
• License: CC0
• Package source code on Github
• Submit Bugs and feature requests

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

Installation

Install the development version directly from Github

library(devtools)
install_github("knitcitations", "cboettig")

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

Quick start

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

library(knitcitations)
newbib()

r cite_options(linked=FALSE)

Cite by DOI

Cite an article by DOI and the full citation information is gathered automatically.

citep("10.1890/11-0011.1")

Typically this is done with knitr's inline code syntax, creating a parenthetical citation in the text like this r citep("10.1890/11-0011.1"). We display the command in code blocks only for documenting purposes here. citep provides a parenthetical citation; a in-text citation is generated with citet, such as this sentence cites r citet("10.1890/11-0011.1").

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("http://knowledgeblog.org/greycite")

to generate the citation to the Greycite tool.

Cite from a bibtex file

If we have a bibtex file, we can cite such articles by those keys as well. To demonstrate, let's first create a bibtex file with the citation information for some R packages, using the bibtex package utilities (a dependency of knitcitations):

write.bibtex(c("Yihui2013" = citation("knitr"), "Boettiger2013" = citation("knitcitations")))
bib <- read.bibtex("knitcitations.bib")

Now we can generate citations from bib

citep(bib[[2]])
citep(bib["Yihui2013"])

Re-using Keys

When the citation is called, a key in the format LastNameYear is automatically created for this citation, so we can now continue to cite this article without remembering the DOI, using the command:

citep("Abrams2012")

Note that a custom key can also be given by naming the DOI, such as citep(c(AbramsEtAl="10.1890/11-0011.1")).

Displaying the final bibliography

At the end of our document we can generate the traditional "References" or "Works Cited" list in a knitr block using the chunk option results='asis' to display as text rather than code:

bibliography()

Other formats can be given as options to bibliography, as described in the help documentation, ?bibliography. For instance, we can specify the format as "markdown". The custom formats "markdown" and "rdfa" take an additional argument, "ordering", which can specify what elements we want to print and what order they should be given in. For instance, we can omit everything but the authors, year, and journal, given in that order:

bibliography("markdown", ordering=c("authors", "year", "journal"))

(Note that since version 0.5, "markdown" is the default and can be omitted)

Links and tooltips

In-text citations are now linked by default to the article. We can turn this on or off in a single citation like so: citep("Abrams2012", linked=TRUE), creating the citation r citep("Abrams2012", linked=TRUE). We can toggle this behavior on or off globally using cite_options(linked=TRUE) at the beginning of our document.

Using the popular javascript library from bootstrap, we can tell knitcitations to include a javascript tooltip on mouseover. (This effect will not work inside a github repo due the the lack of the javascript library, but can easily be deployed on a website, see r citet("http://carlboettiger.info/2013/02/22/semantic-citations-for-the-notebook-and-knitr.html", cito="discusses"). This function is off by default can be toggled on or off in the same way, cite_options(tooltip=TRUE).

Semantics

CiTO

Additional semantic markup can be added the the citations themselves, such as the reason for the citation. For instance, we can identify that we have used the method from r citet("10.1186/2041-1480-1-S1-S6", cito = "usesMethodIn") with the inline command citet("10.1186/2041-1480-1-S1-S6", cito = "usesMethodIn").

More discussion on using knitcitations for CITO and semantic markup can be found in r citet("http://carlboettiger.info/2013/02/22/semantic-citations-for-the-notebook-and-knitr.html", cito="usesMethodIn").

knitcitations documentation built on Jan. 13, 2021, 9:57 a.m.