Cite Tools

Advanced bibliography for Pandoc and Quarto

Cite Tools is an extension of the Quarto Open-Source Scientific and Technical Publishing System, built upon Pandoc and compatible with any version above 2.17, that bundles together several Lua filters 🌙 to introduce advanced bibliography features.

Why a bibliography extension?

Users of the jurassic BibTeX would probably be exceptionally pleased with the speed and reliability of Pandoc Citeproc. Apart from being (a lot) faster, Citeproc will produce the same output across all formats supported by Pandoc, which amount to over 60, including HTML, LaTeX, and Word.

Out-of-the-box, however, Citeproc does not provide common BibTeX functionalities, such as the ability to split the bibliography into multiple sections, or the ability to cite arbitrary fields of the references (e.g. citetitle, citeauthor, citefield). It also lacks the interesting backref option afforded by BibTeX and HyperRef, which allows for the creation of linked indexes of citations.

Luckily, Citeproc is extensible, and this extension aims to provide a solution to these limitations and, hopefully, allow Pandoc and Quarto users to completely replace BibTeX/BibLaTeX with Citeproc. It will allow the user to easily create multiple bibliographies (or bibliographies with multiple sections, such as primary and secondary sources), cite arbitrary fields of the references¹, and create linked indexes of citations². All of this with very little configuration needed.

Also, with the advent of Quarto, it has become easier for those not well-versed Lua or Pandoc to use extensions such as this one! So, why not?!

New to Quarto ?

Quarto is an open-source scientific and technical publishing system. Visit the getting started guide to download and install. Once installed, you can use it to create, build, and preview your documents.

I highly recommend visiting the Tutorial: Hello, Quarto. You’ll learn how to create a document, build it, and preview it. You will also be taken to the excellent extensions for VS Code and RStudio that will make your life easier.

Quarto Quickstart 🚀

• On macOS (), use Homebrew to brew install quarto.
• On Windows (), use Chocolatey to choco install quarto.
• On Linux (), use your package manager to install quarto.

Find out more at Awesome Quarto, Quarto Extensions, Quarto on Github, RStudio Community, Stack Overflow, Twitter.

New to Pandoc ?

Pandoc is a universal document converter developed by John MacFarlane, professor of philosophy, that is at the core of Quarto. To learn more about it, see the Pandoc User’s Guide . You can install Pandoc as a standalone application, but it will also inevitably be included in any Quarto instalation.

Make sure to check Pandoc-Discuss in case you have unsolved questions. You can also ask questions on Pandoc at Stack Overflow.

Installation 📦

If the prospect of typing something on the command line seems daunting, or if you simply need a sample, you can download the citetools repository directly and open it in VSCode to see a working example.

Otherwise, create a new project and install it using:

quarto install extension bcdavasconcelos/citetools

Activate it by adding citetools to the _quarto.yml file in the filters section.

filters:
  - citetools

Quickstart 🚀

Add the path to the bibliography files to the document YAML header or _quarto.yml 📁

---
bibliography_bib-name: path/to/bibfile.bib
bibliography_other-bib-name: path/to/otherbibfile.bib
---

Place the corresponding placeholders where they should be printed in the document body 🖨️

::: {#refs_bib-name}
:::

::: {#refs_other-bib-name}
:::

You’re ready to rock. 🤘

Usage 📖

Cite references as you normally do in Pandoc and they will be linked 🔗 and backlinked 🔗 to the bibliography 📚

[@citekey]

Use [@Citekey]{.csl_field} to arbitrarily print specific fields instead of the usual Author-Date format. This is useful for printing the title of a book or the name of a journal in the text. 🎯

[@citekey]{.author}
[@citekey]{.title}
[@citekey]{.original-title}

Append the field name with a dot to avoid creating a link to the bibliography in this particular citation📍

[@citekey]{.author.}

This can also be done globally 🌐 by setting link-fields: false in the metadata³. This is useful if you want to print the title of a book or the name of a journal in the text, but don’t want to create a link to the bibliography.

---
link-fields: false
---

Documentation 📚

This Quarto-powered website provides documentation for the following filters:

• multiple-bibliographies
• cite-field
• citation-backlinks

In the future, we plan to add documentation for the following filters:

• section-bibliographies
• recursive citeproc

Contributing 🤝

If you have suggestions for other filters, improvements to the existing ones, or bug reports, please open an issue at the citetools repository .

Acknowledgments 🙏

• Albert Krewinkel, for creating Pandoc filters.
• John MacFarlane, for creating Pandoc.
• The community of Quarto and Pandoc developers and users.

Footnotes

1. In the official nomenclature, CSL has variables, BibTeX has fields, and RIS has tags. As a general rule, we have stuck to the term fields.

2. Linked glossaries can also easily be created by dressing it as bibiography

3. If link-citations is false then link-fields will also default to false.

Citation

BibTeX citation:

@online{vasconcelos2023,
  author = {Vasconcelos, BCDA},
  title = {Cite {Tools}},
  date = {2023},
  url = {https://bcdavasconcelos.github.io/citetools/},
  langid = {en}
}

For attribution, please cite this work as:

Vasconcelos, BCDA. 2023. “Cite Tools .” 2023. https://bcdavasconcelos.github.io/citetools/.