Citations in Quarto

This manual expects the use of RStudio because it is highly integrated with Quarto and Zotero. For example, RStudio automatically generates and updates a bibliography file when inserting citations, and this bibliography will be created based on the CSL file you specify in the YAML header.

That said, these instructions also cover text-only editing options that should be applicable to editing your document in any text editor. However, you should note that other text editors may not have the same built-in functionality, and may require adjustments to your workflow.

If you choose to stick with a different text editor, you can check out the Tutorial: Authoring Quarto documentation page for further reading.

Background

Before discussing the approaches for inserting citations, we first need to cover references.bib files and “citation keys.”

What are references.bib Files?

A references.bib file is a BibTeX file that contains all of the references you want to cite in your document. This file is used to generate the bibliography at the end of your document, and it is necessary to include this file in your project directory in order to insert citations. You can create this file manually, but it is generally easier to export your references from a citation manager or allow RStudio to manage the creation of the file for you.

When using a references.bib file with a Quarto document, you must specify the name of the file in the YAML header of your document like this:

---
title: "Your project title"
bibliography: references.bib
---

Note that you can name the file something other than references.bib, but you must ensure that the name of the file you specify in the YAML header matches the name of the file you have saved in your project directory.

You will rarely need to edit the references.bib file directly, but you can open it in a text editor to see the structure of the file. An example of an entry inside of a references.bib file might look like this:

@article{horst2022,
    title = {Palmer Archipelago Penguins Data in the palmerpenguins R Package - An Alternative to Anderson's Irises},
    author = {Horst, Allison M. and Hill, Alison Presmanes and Gorman, Kristen B.},
    year = {2022},
    month = {06},
    date = {2022-06-21},
    journal = {The R Journal},
    pages = {244--254},
    volume = {14},
    number = {1},
    doi = {10.32614/RJ-2022-020},
    url = {https://doi.org/10.32614/RJ-2022-020/}
}

What is a Citation Key?

Citation keys are unique identifiers for each reference in your bibliography. They are used to insert citations in your document and are typically generated automatically by your text editor. These keys are necessary because they connect your citations to the correct entry in the references.bib file.

Extending the references.bib example, you would cite the Palmer Penguins data set from 2022 by Allison Horst with the citation key @horst2022. You would use this citation key in your document to insert a citation to this reference.

RStudio generates a citation key for each new item you include in a document, and they typically follow the format @authorYear or @authorYearLetter when there are multiple references matching the format. 1 These keys can be customized to your liking, but this should be done only prior to using them the first time.2

Inserting Citations

The General Approach

The method for inserting citations in Quarto documents described in the first section is the most general approach, and will work for any text editor. Note that if you are using RStudio, you should use the “Source” editing mode for this method. You can use the “Visual” editor to insert citations on a point-and-click basis, which is covered in the next section.

Referencing by Citation Key

When you insert a citation in your document, you will use the citation key of the reference you want to cite.

If you export a library from Zotero, however, a different default method for generating the citation keys will be used. These differences will be discussed in the following sub-sections, RStudio Visual Editor and Manual Entry.

You can insert a citation in your document by using the @ symbol followed by the citation key of the reference you want to cite. For example, I have saved the Zotero Quick Start guide to my Zotero library for this tutorial, and in order to to cite this guide, I would use the citation key [@zotero] in my document. The text would look like this:

“Items can be assigned tags. Tags are named by the user. An item can be assigned as many tags as is needed.”[@zotero]

This will insert a citation that is displayed in your document like this:

“Items can be assigned tags. Tags are named by the user. An item can be assigned as many tags as is needed.”(Zotero, n.d.)

Note that the citation key can be inserted in two ways: with or without brackets [], which yield formatting differences. A citation without brackets, @zotero, will appear inline as “Zotero (n.d.)”, while a citation with brackets, [@zotero], will appear as “(Zotero, n.d.)”.

RStudio Visual Editor

If you are using RStudio’s visual editor, you can insert a citation by clicking on the “Insert” menu at the top of the screen and selecting “Citation.” This will open a dialog box where you can search for the reference you want to cite by typing in the author’s name, title, or other identifying information. Once you have found the reference you want to cite, you can click on it to insert the citation into your document.

Note that this process is simply a “visual” short code for inserting the citation key into your document, but is more convenient as it lets you interactively search through your Zotero library and dynamically add citations to your references.bib file.

A new, empty project will look similar to this image. Note that you must be in the Visual editor mode in order to see the Insert button. Press this button.

After opening the Insert drop-down section, scroll down to the Citation option and open this.

This should open a plugin that allows you to search your Zotero library as well as PubMed, CrossRef, and directly by DOI numbers (in case you haven’t already saved something to your Zotero library). Open the Zotero folder relevant to your project, the “Zotero Tutorial” in this example.

Press once on the citation you would like to insert. Note taht the citation will be highlighted, and there is now a short tag in the bottom left. This is the citation key that will be used by default.

If you’d like to edit the key to something more memorable or informative, press on the pencil button and edit away. In this example, the citation key has been changed to @zotero-guide.

Note that citation key changes must be done the first time you include a new citation and you cannot have spaces in the name. Press Insert when done.

Your citation is now included inline in the document. Moreover, the bibliography is now connected to your Quarto document with the addition of the bibliography: references.bib text to the yaml header. RStudio will either create or update the references.bib file for you.

A version of the example document rendered as a PDF. Note that, while the bibliography is included in the output document, it is not formatted as a proper “References” section. We will revisit this shortly.

Manual Entry

If you are not using RStudio as your text editor, you can still insert citations manually by following these steps:

  1. Export your bibliography from Zotero as a BibTex file
  2. Save this file in your project directory as references.bib
  3. Add the following to your YAML header: bibliography: references.bib
  4. Insert the citations using the citation keys found in the references.bib file. These can be found in the BibTex file you exported from Zotero as the first line for each entry.

Adding a Bibliography

As mentioned in the previous instructions for inserting citations, RStudio will automatically generate a bibliography file for you when you insert a citation. This bibliography file will be automatically updated to include any new citations you add, and you must define the bibliography file to use for your document(s) using the bibliography: <your-references-file.bib> line in the YAML header like below.

RStudio will generate a file named references.bib by default if you have not already created a bibliography file. You can change the name of this file to whatever you like, but you must ensure that the name of the file you specify in the YAML header matches the name of the file you have saved in your project directory.

---
title: "My Document"
bibliography: references.bib
---

Adding References at the End of the Document

After inserting your citations, you presumably will want a well-formatted bibliography or references section available at the end of your document. “By default, Pandoc will automatically generate a list of works cited and place it in the document if the style calls for it. It will be placed in a div with the id refs if one exists. (Quarto Team, n.d.):”

### References

::: {#refs}
:::

This will generate a “References” section at the end of your document with the bibliography formatted according to the citation style you have specified in the YAML header. An example of this can be found at the bottom of this page!

Changing Citation Style

The Citation Style Language page talked in depth about the different citation styles available to you. You can change the citation style of your document by adding the csl: <your-csl-file.csl> line to the YAML header like below:

---
title: "My Document"
bibliography: references.bib
csl: your-csl-file.csl
---

This will change the citation style of your document to the style specified in the CSL file you provide. You can find CSL files for different citation styles on the Citation Styles Library website.

Note that the csl: field can also be a link directly to a CSL file online. For example, the following YAML header will use the Nature citation style:

---
title: "My Document"
bibliography: references.bib
csl: https://www.zotero.org/styles/nature
---

A Note on Updating Citations in Zotero

A current shortcoming with inserting citations into Quarto documents is that the bibliography does not automatically update when you update the references in Zotero.

That is, if you make changes to the citations within Zotero, you may need to delete the references.bib file and reinsert the citations to force update the bibliography in your project. This sounds a bit complicated, but simply deleting the references.bib file and reinserting a single citation will prompt RStudio to regenerate the references.bib file with the updated references.

Automatic Updates in the Future?

An issue requesting that the bibliography automatically update when references are updated in Zotero was previosuly opened in the RStudio GitHub repository, but it was closed without being addressed. you can find the issue here. you can, however, comment that you’d like to see this feature implemented in the future ;).

References

Quarto Team. n.d. “Citations in Quarto: Bibliography Generation.” https://quarto.org/docs/authoring/citations.html#bibliography-generation.
Zotero. n.d. “Quick_start_guide [Zotero Documentation].” https://www.zotero.org/support/quick_start_guide.
Back to top

Footnotes

  1. The citation keys used in RStudio use Pandoc citation syntax. You can find more information on Pandoc citation syntax in the Pandoc documentation on citations and citation syntax.↩︎

  2. If needed, you can edit the citation keys in the references.bib file directly. However, you must ensure that the citation key is unique and does not contain any spaces or special characters.↩︎