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.
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
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
Footnotes
They are not, however, widely supported, so you’ll probably be stuck with
BibTeX
orBibLaTeX
in some way or other anyway.↩︎
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}
}