3 Citations and cross-references
3.1 Citations
The usual way to include citations in an R Markdown document is to put references in a plain text file with the extension .bib, in BibTex format.3
Then reference the path to this file in index.Rmd’s YAML header with bibliography: example.bib
.
Most reference managers can create a .bib file with you references automatically.
However, the by far best reference manager to use with R Markdown is Zotero with the Better BibTex plug-in, because the citr
plugin for RStudio (see below) can read references directly from your Zotero library!
Here is an example of an entry in a .bib file:
@article{Shea2014,
author = {Shea, Nicholas and Boldt, Annika},
journal = {Trends in Cognitive Sciences},
pages = {186--193},
title = {{Supra-personal cognitive control}},
volume = {18},
year = {2014},
doi = {10.1016/j.tics.2014.01.006},
}
In this entry highlighed section, ‘Shea2014’ is the citation identifier.
To default way to cite an entry in your text is with this syntax: [@citation-identifier]
.
So I might cite some things (Shea et al. 2014; Lottridge et al. 2012).
3.1.1 PDF output
In PDF output, the bibliography is handled by the OxThesis LaTeX template.
If you set bib-humanities: true
in index.Rmd, then in-text references will be formatted as author-year; otherwise references will be shown as numbers.
If you choose author-year formatting, a number of variations on the citation syntax are useful to know:
- Put author names outside the parenthesis
- This:
@Shea2014 says blah.
- Becomes: Shea et al. (2014) says blah.
- This:
- Include only the citation-year (in parenthesis)
- This:
Shea et al. says blah [-@Shea2014]
- Becomes: Shea et al. says blah (2014)
- This:
- Add text and page or chapter references to the citation
- This:
[see @Shea2014, pp. 33-35; also @Wu2016, ch. 1]
- Becomes: Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1).
- This:
3.1.2 Gitbook output
In gitbook output, citations are by default inserted in the Chicago author-date format.
To change the format, add csl: some-other-style.csl
in index.Rmd’s YAML header.
You can browse through and download styles at zotero.org/styles.
3.1.3 Insert references easily with the citr
add-in
For an easy way to insert citations, try the citr
RStudio add-in (Figure 3.1).
You can install this add-in by typing install.packages("citr")
in the R Console.

Figure 3.1: The citr
add-in
3.2 Cross-referencing
We can make cross-references to sections within our document, as well as to figures (images and plots) and tables.
The general cross-referencing syntax is \@ref(label)
3.2.1 Section references
Headers are automatically assigned a reference label, which is the text in lower caps separated by dashes. For example, # My header
is automatically given the label my-header
. So # My header
can be referenced with \@ref(my-section)
Remember what we wrote in section 3.1?
We can also use hyperlink syntax and add # before the label, though this is only guaranteed to work properly in HTML output:
- So if we write
Remember what we wrote up in [the previous section](#citations)?
- It becomes Remember what we wrote up in the previous section?
3.2.1.1 Creating custom labels
It is a very good idea to create custom labels for our sections. This is because the automatically assigned labels will change when we change the titles of the sections - to avoid this, we can create the labels ourselves and leave them untouched if we change the section titles.
We create custom labels by adding {#label}
after a header, e.g. # My section {#my-label}
.
See our chapter title for an example. That was section 3.
3.2.2 Figure (image and plot) references
- To refer to figures (i.e. images and plots) use the syntax
\@ref(fig:label)
- GOTCHA: Figures and tables must have captions if you wish to cross-reference them.
Let’s add an image:
knitr::include_graphics("figures/captain.jpeg")

Figure 3.2: A marvel-lous meme
We refer to this image with \@ref(fig:captain)
.
So Figure 3.2 is this image.
3.2.3 Table references
- To refer to tables use the syntax
\@ref(tab:label)
Let’s include a table:
knitr::kable(cars[1:5,],
caption="Stopping cars")
speed | dist |
---|---|
4 | 2 |
4 | 10 |
7 | 4 |
7 | 22 |
8 | 16 |
We refer to this table with \@ref(tab:cars-table2)
.
So Table 3.1 is this table.
And in Table 2.1 we saw more or less the same cars table.
3.2.4 Including page numbers
Finally, in the PDF output we might also want to include the page number of a reference, so that it’s easy to find in physical printed output.
LaTeX has a command for this, which looks like this: \pageref{fig/tab:label}
(note: curly braces, not parentheses)
When we output to PDF, we can use raw LaTeX directly in our .Rmd files. So if we wanted to include the page of the cars plot we could write:
- This:
Figure \@ref(fig:cars-plot) on page \pageref(fig:cars-plot)
- Becomes: Figure 2.4 on page
3.2.4.1 Include page numbers only in PDF output
A problem here is that LaTeX commands don’t display in HTML output, so in the gitbook output we’d see simply “Figure 2.4 on page.”
One way to get around this is to use inline R code to insert the text, and use an ifelse
statement to check the output format and then insert the appropriate text.
- So this:
`r ifelse(knitr::is_latex_output(), "Figure \\@ref(fig:cars-plot) on page \\pageref{fig:cars-plot}", "")`
- Inserts this (check this on both PDF and gitbook):
Note that we need to escape the backslash with another backslash here to get the correct output.
3.3 Customising your thesis’ front matter ’n stuff
3.3.1 Shorten captions shown in the list of figures (PDF)
You might want your list of figures (which follows the table of contents) to have shorter (or just different) figure descriptions than the actual figure captions.
Do this using the chunk option fig.scap
(‘short caption’), for example {r captain-image, fig.cap="A very long and descriptive (and potentially boring) caption that doesn't fit in the list of figures, but helps the reader understand what the figure communicates.", fig.scap="A concise description for the list of figures"
3.3.2 Shorten captions shown in the list of tables (PDF)
You might want your list of tables (which follows the list of figures in your thesis front matter) to have shorter (or just different) table descriptions than the actual table captions.
If you are using knitr::kable
to generate a table, you can do this with the argument caption.short
, e.g.:
knitr::kable(mtcars,
caption = "A very long and descriptive (and potentially
boring) caption that doesn't fit in the list of figures,
but helps the reader understand what the figure
communicates.",
caption.short = "A concise description for the list of tables")
3.3.3 Shorting the running header (PDF)
You might want a chapter’s running header (i.e. the header showing the title of the current chapter at the top of page) to be shorter (or just different) to the actual chapter title.
Do this by adding the latex command \chaptermark{My shorter version}
after your chapter title.
For example, this chapter’s running header is simply ‘Cites and cross-refs,’ because it begins like this:
# Citations and cross-references {#cites-and-refs}
\chaptermark{Cites and cross-refs}