July 2021

Citations have been carefully designed in such a way that users and Elisp tinkerers will be able to easily adapt and extend it to fit their needs. To that end, Org Cite (or OC for short) has been split into two halves:

• oc.el which defines the syntax and provides some machinery to interact with citations
• Citation processors which interface with oc.el to produce nicely-formatted citations to be inserted in your bibliography, within the text, and even rendered in the buffer²

There are four capabilities that Org Cite uses the processors for

1. Inserting and editing citations
2. Following citations to their definition
3. Fontifying the citations in the buffer
4. Exporting the citations

Each capability can have a particular citation processor assigned, independently of the others. Out of the box, Org uses the basic processor for all of these tasks.

The basic citation processor is one of four currently bundled with Org:

• basic, which has no dependencies and provides all four capabilities. It export to all formats, but only provides very simple citations.
• biblatex and natbib, which provide the export capability to create citations via Biber and (to a lesser extent) natbib, but only for LaTeX.
• csl, which provides the export capability using the Citation Style Language, and exports to HTML, LaTeX, Org, and plain text (with an open issue for ODT) — but depends on citeproc.el.

This provides a solid foundation for other packages to build off, and despite Org Cite being yet to be released or documented in the manual we are already seeing the development of packages like org-ref-cite (by John Kitchin).

To get started with Org Cite, we must have some form of bibliography. This can either be a BibTeX file or a CSL-JSON file.

As an example, say we have a file orgcite.bib containing the following

@article{OrgCitations,
         author={org, mode and Syntax, Citation and List, Mailing and Effort, Time},
         journal={Journal of Plain Text Formats},
         title={Elegant Citations with Org-Mode},
         year={2021},
         month={7},
         volume={42},
         number={1},
         pages={2-3}}

First we need to let Org know about this bibliography file (which must have a .bib, .bibtex, or .json extension), which we do either via the #+bibliography keyword, or the variable org-cite-global-bibliography.

#+bibliography: orgcite.bib

Once you have a bibliography source, you can start referencing to your heart’s content! The basic citation syntax is as follows:

Using the default style [cite:@OrgCitations] produces (org et al. 2021). For more information on the styles currently available, see 1.

Finally, to insert a bibliography somewhere, we just need to insert the #+print_bibliography keyword, like so:

#+print_bibliography:

So, to summarise, all one needs to get started is:

#+bibliography: references.bib
[cite:@key]
#+print_bibliography:

That’s it! 🎉

Don’t let the simplicity in the examples above fool you, the new syntax is quite capable of expressing more complex forms. Here’s the full version of the new cite syntax:

• The style and variant determine what form the exported citation takes
• The common prefix and suffix and put at the start and end of the generated citation, respectively
• The citation key refers to a Bib(La)TeX or CSL-JSON key
  • The citation prefix and suffix are put before and after the reference to the key
  • Some citation processors recognise locators, which refer to a particular part of the work, for example: p. 7 to refer to page 7.

Using the default CSL citation style (Chicago author-name) [cite/l/b:see @OrgCitations pp. 7 for fun] becomes see 7 for fun.

The citation styles and variants, and recognised locators are handled by the citation processors. Org cite’s bundled processors currently supports the following citation styles.

The CSL processor supports the following locators:

• book, bk., bks.
• chapter, chap., chaps.
• column, col., cols.
• figure, fig., figs.
• folio, fol., fols.
• number, no., Os.
• line, l., ll.
• note, n., nn.
• opus, op., opp.
• page, p, p., pp.
• paragraph, para., paras., ¶, ¶¶, §, §§
• part, pt., pts.
• section, sec., secs.
• sub verbo, s.v., s.vv.
• verse, v., vv.
• volume, vol., vols.

The style of the citations and the bibliography depend on three things:

1. The citation processor used
2. The citation style
3. The bibliography style

The citation processor is automatically selected based on org-cite-export-processors based on the export format being used, but can be set on a per-document basis via the #+cite_export keyword. Here, I shall use the csl processor,

#+cite_export: csl

With org-cite-export-processors, you can also set the bibliography and citation style by giving a triplet of parameters (PROCESSOR BIBLIOGRAPHY-STYLE CITATION-STYLE) instead of just the processor. You can also use this triplet of values with the #+cite_export keyword

#+cite_export: processor bibliography-style citation-style

There are also some more options about how the bibliography is produced. These options are handled by the active citation processor. For example, while the CSL processor does not currently support any options, the BibLaTeX processor passes options to a \printbibliography command, allowing for the following:

#+print_bibliography: :section 2 :heading subbibliography
#+print_bibliography: :keyword abc,xyz :title "Primary Sources"

Citeproc is currently available on MELPA, and so can be installed via your package manager of choice so long as MELPA is included in your package-archives. When available, it will be automatically loaded by oc-csl.el.

It currently supports exporting to:

• HTML
• LaTeX
• Org
• Plain text

Should you be interested in other formats, know that Citeproc is designed to easily support adding new formats (see citeproc-formatters.el for examples).

Citeproc can currently retrieve bibliographic information from the following formats:

• CSL-JSON
• Bib(La)TeX
• org-bibtex

Though support for Bib(La)TeX and org-bibtex is rudimentary compared to CSL-JSON.

When exporting, you can set the style by providing a path to CSL style files, either absolute or relative to org-cite-csl-styles-dir. For example, if I download apa.csl I can use it like so:

#+cite_export: csl ~/Downloads/apa.csl

When no style is given org-cite-csl--fallback-style-file will be used, which defaults to a bundled Chicago author-date style.

There are quite a few reference managers available, however, the list rapidly shrinks if you restrict yourself to applications which are:

• somewhat feature-rich
• open source software
• not owned by a parasitic company³

Zotero is a good option, and if you’re using it it’s quite easy to use it with Org Cite. Out of the box, you can tell it to export your library, or parts of it, to a .bib file and automatically keep it in sync. I’d recommend installing the Better BibTeX extension though.

Zotero also works well with CSL. In addition to supporting CSL-JSON exports, Zotero also features an easy way to install CSL styles within the preferences.

Since these files are put under ~/Zotero/styles, you can use them with Org Cite and Citeproc simply by setting org-cite-csl-styles-dir to the Zotero styles directory.

(setq org-cite-csl-styles-dir "~/Zotero/styles")

To then use the citation style defined by ~/Zotero/styles/apa.csl one can then simply refer to apa.csl when using the #+cite_export keyword.

#+cite_export: csl apa.csl

Org Cite has only just been merged in the past month, and is yet to be included in an Org release, but we’re seeing a tremendous degree of community interest. There are already promising developments with third-party packages, such as bibtex-actions and org-ref-cite. I can’t wait to see how the ecosystem continues to develop 😃.