The Basics of Pandoc Citeproc

Before we can begin with advanced bibliography features in Pandoc and Quarto, we need to get some basics out of the way, as this will be the foundation for the advanced bibliography features.

Official documentation

See the official documentation on citations at Pandoc and Quarto.

Before you can use Cite Tool, you will need a bibliography file. Although nothing stops you from keeping bibliography files manually, this is not advisable for anything other than very small-scale projects. For everything else, consider using software such as Zotero, JabRef, Bookends, Bibdesk, Endnote (and see also this comparison on Wikipedia). These programs allow you to edit your bibliography and easily export it in the desired format.

The most common format, and one of the oldest, is called BibTeX (or BibLaTeX); others, more recent, include CSL-JSON and CSL-YAML. These latter are preferable since they perform much faster on Pandoc and Quarto (being the format used to represent the bibliography internally)1.

You can also use shared bibliographies on Github (just provide Pandoc with the URL to the raw file) or shared Zotero libraries, which can be downloaded using the API by accessing the link below, where LibraryID should be replaced by the 7-digit code in the middle of the library URL.

https://api.zotero.org/groups/LibraryID/items?format=bibtex&limit=999

How to Setup a Simple Bibliography

Set up the bibliography of a document by including the path to the bibliography file in the YAML header.

bibliography: path/to/bibfile.bib
csl: path/to/cslfile.csl # optional

If no CSL file is supplied, Pandoc will default to the Chicago Author-Date style. It is advisable to use a CSL file, as it will ensure that the bibliography is formatted according to the style of your choice. You can find a list of available CSL styles in the Citation Styles Github Repo and you can edit them with the CSL Visual Editor or using Zotero.

It is also advisable to keep the bibliography and CSL style files in the default Pandoc folder:

  • macOS: ~/.local/share/pandoc
  • Linux: ~/.local/share/pandoc
  • Windows: C:\Users\USERNAME\AppData\Roaming\pandoc

You can find the path to your Pandoc folder by running the following command in your terminal:

pandoc --version

This way, you can use the same bibliography and CSL-style files in all your documents. Alternatively, you can keep the files in the same folder as your document, which is the approach favored by Quarto.

If the Pandoc folder needs to be shared among multiple devices, you can use a cloud service like Dropbox or Google Drive to store the files and use a symbolic link to place the files in the Pandoc folder. For example, if you are using Dropbox, you can run the following command in your terminal:

ln -s ~/Dropbox/Pandoc ~/.local/share/pandoc

The symbolic link will appear as a shortcut pointing to the Dropbox folder and any changes will be reflected in both locations.

If the files are in the default Pandoc folder or the same folder as the document, you can simply supply the file name:

bibliography: bibfile.bib
csl: cslfile.csl

You can, but you don’t have to, place a div at the end of the document or where you want the bibliography to be printed.

::: {.references}
:::

How to cite in Pandoc

The vanilla Pandoc and Quarto’s Citeproc environment is powerful and its syntax is simple. It uses @Citekey for Author (Date)and [-@Citekey] for (Date).

The advantage of this markup syntax lies in its simplicity and compatibility with all formats supported by Pandoc, a universal document converter.

Here are some examples:

@Aubenque1961a says that… […] …on the deliberations of the prudent person [-@Aubenque1961a].

Aubenque (1961) says that… […] …on the deliberations of the prudent person (1961).

The citation key is optionally followed by a locator, which can be a page number, a line number, a chapter number, or a section number, preceded by a comma.

…on the deliberations of the prudent person [-@Aubenque1961a, p.15] .

…on the deliberations of the prudent person (1961, 15).

Syntax Summary

Variations of the Citation syntax
Syntax Output
@Aubenque1961a Aubenque (1961)
[@Aubenque1961a] (Aubenque 1961)
[@Aubenque1961a, p.15] (Aubenque 1961, 15)
[-@Aubenque1961a] (1961)
[-@Aubenque1961a, p.15] (1961, 15)

Now that we have the basics covered, let us see what Cite Tools can do for us.

References

Aubenque, Pierre. 1961. “Sur La Notion Aristotélicienne d’aporie.” In Aristote Et Les Problèmes de Méthode, edited by S. Mansion. Louvain: Publications Universitaires.

Footnotes

  1. They are not, however, widely supported, so you’ll probably be stuck with BibTeX or BibLaTeX in some way or other anyway.↩︎

Citation

BibTeX citation:
@online{vasconcelos2023,
  author = {Vasconcelos, BCDA},
  title = {The {Basics} of {Pandoc} {Citeproc}},
  date = {2023},
  url = {https://bcdavasconcelos.github.io/citetools/docs_qmd/01-basics.html},
  langid = {en}
}
For attribution, please cite this work as:
Vasconcelos, BCDA. 2023. “The Basics of Pandoc Citeproc.” 2023. https://bcdavasconcelos.github.io/citetools/docs_qmd/01-basics.html.