Citation handling in Emacs

Published Wednesday 5 April 2023 at 12:00 BST

Until recently Emacs's Org mode had no native support for citation handling, which was done by third-party packages such as Org Ref. But as of Org version 9.5, released in October 2021, native citation handling has been provided by the built-in library Org Cite. Org Cite is intentionally basic, providing no more than core citation-handling functionality. On its own it has nothing like the capabilities of Org Ref. But it can be extended (this is Emacs, after all) with the Citar package. In turn, further packages can be used to enhance the combined functionality and appearance of Org Cite and Citar. Together these provide a near-complete citation-handling framework for Org.

The official documentation for Org Cite is available in the Org manual, and a more detailed description given in This month in Org. However, the documentation is incomplete, and there is no tutorial available. This makes it difficult for the newcomer to discover exactly what Org Cite does and how to use it. At least that was my experience when I first encountered Org Cite. Nevertheless, I have pieced together an understanding of its functionality and API, which I summarize here. All code has been tested using Emacs 28.1 and Org 9.6.1.

Org Cite

The package Org Cite, written by Nicolas Goaziou, defines a citation syntax and allows the processing in Org of:

  • citation insertion,
  • citation following,
  • citation activation, and
  • citation exporting.

Citations must obey a syntax specific to Org, in the same way that citations in Latex must obey their own Latex-specific syntax (\cite[prefix][suffix](citationKey), \citep[prefix][suffix](citationKey), etc.). The term `citation insertion' refers to the process of automatically inserting citations using Emacs M-x commands. `Citation following' refers to the process of interacting with (opening, editing, copying, etc.) files and links associated a citation's reference. `Citation activation' refers to a citation's fontification, tooltip preview, etc. And `Citation exporting' refers to the proper formatting of a citation when exporting an Org document to some other format (HTML, Latex, Markdown, etc). The export processor deals with the styling of a citation and its reference, ensuring that it follows the author-date style, Vancouver style, etc.

Specifying a reference source

Before you can do anything with citations you must specify a reference source in the form of a bibliograpy file in BibTex or CSL-JSON format. To do this you can use the export keyword BIBLIOGRAPHY, which may be repeated an arbitrary number of times to specify an arbitrary number of bibliography files. At some point in your Org file (at the top if you are tidy) add the following.

#+BIBLIOGRAPHY: Path/To/bibliographyFile

You may specify a global bibliography, available to all Org files by setting the variable org-cite-global-bibliography. To do so, use M-x set-variable RET org-cite-global-bibliography RET ("Path/To/globalBibliographyFile") RET or add the following to your init file (.emacs, emacs.el, or .emacs.d/init.el).

(setq org-cite-global-bibliography '("Path/To/globalBibliographyFile"))

In this case, the BIBLIOGRAPHY export keyword is uneccessary, though it may be used to specify additional bibliographies. For the sake of concreteness, suppose that the bibliography file, called bibliographyFile, is in BibTex format, that it lives in the same directory as your Org file, and that it reads as follows.

@thesis{broglie1924,
  type = {phdthesis},
  title = {Recherches sur la th\'eorie des Quanta},
  author = {de Broglie, Louis},
  date = {1924-11-25},
  institution = {{Migration---universit\'e en cours d'affectation}},
  url = {https://theses.hal.science/tel-00006807},
  file = {Path/To/pdfFile}
}

Citation syntax

You insert citations in-line, at the point required. The citation syntax is as follows, where the inner square brackets indicate optional arguments.

[cite[/[style][/variant]]:[commonPrefix ;][prefix ]@citationKey[ suffix ][; ... ] [;commonSuffix]]

The style and variant elements specify the formatting of the exported citations when exporting to author-date styles. They are redundant when exporting to numerical styles. The Month in Org provides a description of their allowed values, which I reproduce in Table 1. The commonPrefix element is an arbitrary string specifying the prefix to all references. The prefix element is an arbitrary string specifying the prefix to an individual reference. The citationKey element specifies the BibTex or CSL-JSON key (in this case, broglie1924). The suffix element is an arbitrary string specifying the suffix to an individual reference. Finally, the commonSuffix element is an arbitrary string specifying the suffix to all references.

Table 1: Allowed values of the elements style and variant used to specify author-date citation styles. (Adapted from the table published in This month in Org.) The variant styles are bare (b), without surrounding punctuation, caps (c), with forced initial capitalization, and full (f), without using the et al. shortening of the author list.
Style Variant Export sample Bib(La)TeX NatBib
a author cf caps-full family=Broglie, given=Louis, prefix=de, useprefix=false Citeauthor  
a author f full family=Broglie, given=Louis, prefix=de, useprefix=false citeauthor citeauthor*
a author c caps Family=Broglie, Given=Louis, Prefix=De, Useprefix=False Citeauthor* Citeauthor
a author   family=Broglie, given=Louis, prefix=de, useprefix=false citeauthor* citeauthor
na noauthor b bare 1924   citeyear
na noauthor   (1924) autocite* citeyearpar
n nocite     nocite nocite
t text b bare family=Broglie, given=Louis, prefix=de, useprefix=false 1924   citealp
t text c caps Family=Broglie, Given=Louis, Prefix=De, Useprefix=False (1924) Textcite Citep
t text f full family=Broglie, given=Louis, prefix=de, useprefix=false (1924)   citep*
t text bc bare-caps Family=Broglie, Given=Louis, Prefix=De, Useprefix=False 1924   Citealp
t text bf bare-full family=Broglie, given=Louis, prefix=de, useprefix=false (1924)   citealp*
t text cf caps-full family=Broglie, given=Louis, prefix=de, useprefix=false (1924)   Citep*
t text bcf bare-caps-full family=Broglie, given=Louis, prefix=de, useprefix=false (1924)   Citealp*
t text   family=Broglie, given=Louis, prefix=de, useprefix=false (1924) textcite  
(default) b bare family=Broglie, given=Louis, prefix=de, useprefix=false, 1924 cite citealp
(default) bc bare-caps Family=Broglie, Given=Louis, Prefix=De, Useprefix=False, 1924 Cite Citealp
(default) f full (family=Broglie, given=Louis, prefix=de, useprefix=false, 1924)   citep*
(default) bf bare-full (family=Broglie, given=Louis, prefix=de, useprefix=false, 1924)   citealp
(default) cf caps-full (family=Broglie, given=Louis, prefix=de, useprefix=false, 1924)   Citep*
(default) bcf bare-caps-full (family=Broglie, given=Louis, prefix=de, useprefix=false, 1924)   Citealp*
(default)   (family=Broglie, given=Louis, prefix=de, useprefix=false, 1924) autocite citep

The following is an example of the most basic citation type.

[cite:@broglie1924]

When the Org file is exported using the default export settings this will be rendered as `(family=Broglie, given=Louis, prefix=de, useprefix=false, 1924)'. Next is an example using the `text' style.

[cite/t:@broglie1924]

When the Org file is exported using the default export settings this will be rendered as `family=Broglie, given=Louis, prefix=de, useprefix=false (1924)'. And also an example using prefixes and suffixes.

[cite:see @broglie1924 fig. 4 p. 71 for example]

When the Org file is exported using the default settings this will be rendered as `(see family=Broglie, given=Louis, prefix=de, useprefix=false, 1924 fig. 4 pp. 71 for example)'.

Citation processing

Citation insertion and editing

Citation insertion is done using the command M-x org-cite-insert (C-c C-x @). Use TAB to display a list of references in a new buffer. You may select a reference using the mouse or keyboard. Using the keyboard you may navigate the list using C-n (down) and C-p (up) as normal. Select the reference using RET. Then repeat this process to select additional references. When you have selected all the references you need, enter the citation into the text using RET. You do not appear to be able to search for references using Org Cite alone.

To specify the style use a prefix argument with cite-insert, i.e. use the command C-u M-x org-cite-insert (C-u C-c C-x @). Then select the references as normal. After RET, you will be prompted to specify a citation style and variant. Either enter this directly (following the allowed values shown in Table 1) or use TAB to be presented with a list. Then use RET to enter the citation to the text. As far as I can tell, you cannot insert a prefix, suffix, or locator using org-cite-insert.

To change a citation key place the cursor over it and use M-x org-cite-insert (C-c C-x @). To add a citation key place the cursor before or after an existing citation key and again use M-x org-cite-insert (C-c C-x @). Unfortunately, you cannot delete a citation key or the arguments style and variant without deleting or editing the text directly.

The bibliography may be called with the export keyword PRINT_BIBLIOGRAPHY.

#+PRINT_BIBLIOGRAPHY: 

This keyword takes an optional list of parameters that allows you to modify the content and formatting of the bibliography (including a heading if you do not want to write that heading explicitly). The Org manual has the full details. When the Org file is exported using the default settings this will be rendered as follows.

family=Broglie, given=Louis, prefix=de, useprefix=false (1924). Recherches sur la th\'eorie des Quanta, {Migration - universit\'e en cours d'affectation}.

The following complete Org file is a minimum working example.

#+BIBLIOGRAPHY: bibliography.bib
[cite:@broglie1924]
#+PRINT_BIBLIOGRAPHY:

You can now export to your desired document format using M-x org-export (C-c C-e) to launch the dispatcher interface as usual. The default export processor allow citations to be exported to any file format.

Citation exporting

When an Org document is exported (to HTML, Latex, etc., as described in the Org manual) the citations and bibliography must be properly formatted for the chosen export type. Org Cite has four native export processors that allow this to happen:

The basic and csl processors allow export to all formats, whereas the biblatex, and natbib processors allow export to Latex format only. To use the csl processor you must have the package Citeproc installed. By default, Org Cite uses the basic export processor. To use the others add the following to your init file.

(require 'oc-csl)
(require 'oc-biblatex)
(require 'oc-natbib)

Then specify the export processor using the export keyword CITE_EXPORT. Again, put the following at the top of your Org file.

#+CITE_EXPORT: processor [bibliographyStyle [citationStyle]]

The parameter processor should be set to the name of one of the native export processors (basic, csl, biblatex, or natbib). In the case of the csl processor the optional parameters bibliographyStyle and citationStyle take the file paths Path/To/bibliographyStyleFile and Path/To/citationStyleFile, and in the case of biblatex and natbib they take biblography style names. Without a bibliography style or citation style specified all processors default to the author-date style.

Many bibliography and citation style files, for use with the csl processor, are available at the CSL Style Reposistory and the Zotero Style Repository. You can keep a style file anywhere, but it is convenient to keep all style files in common directory, Path/To/StylesDir. You can then set the variable org-cite-csl-styles-dir to this value by using M-x set-variable RET org-cite-csl-styles-dir RET Path/To/StylesDir RET or adding the following to your init file (.emacs, emacs.el, or .emacs.d/init.el).

(setq org-cite-csl-styles-dir '("Path/To/StylesDir"))

This allows you to specify bibliographyStyle and citationStyle using file paths relative to the directory Path/To/StylesDir. For example, suppose that you wish to use the American Medical Association's version of the numerical Vancouver style of citations and bibliographies (available here) and that you have it available at Path/To/StylesDir/american-medical-association.csl. Specify the export parameters as follows.

#+CITE_EXPORT: csl american-medical-association.csl

When using the bibtex processor you can, for example, specify the Vancouver style as follows.

#+CITE_EXPORT: biblatex vancouver

And when using the natbib processor you can, for example, specify the Kluwer style in the same way.

#+CITE_EXPORT: natbib kluwer

If you only want to insert citations and have them correctly exported, this is all you need to know. However, the remaining citation-activation and citation-following processors allow you to interact with citations within Org and are extremely useful.

Citation following

Once it is inserted, you may interact with a citation using Org's at-point actions. Move the cursor to any point in the citation key or the `@' character preceeding it and use the command M-x org-open-at-point (C-c C-o), as it is done for following links of all kinds in Org. This opens the bibliography file at the resource's entry.

Citation activation

Once complete, a citation will be highlighted in a colour specific to your Emacs theme. Mouse-over will cause the citation text's foreground and background colours to change, again according to your theme's specification. With tooltip-mode enabled (M-x tooltip-mode), mouse-over will also activate the tooltip preview, displaying a summary of the citation's bibliography entry. With tooltip-mode disabled, mouse-over will display the same information in the minibuffer. Non-existent citations (due to, say, a typo or spelling mistake) will be highlighted, again in a colour specific to your theme.

Extending Org Cite

Citation insertion and editing using Org Cite is basic. You cannot kill citations, delete them, reorder them, or change their styles once they have been inserted. Nor can you access files (PDF files, web links, etc.) associated with them other than the bibliography file. In fact, you cannot search your bibliography file when inserting a citation. This additional functionality is provided by the Citar package. Citar may be used in conjuction with the Vertico, Orderless, Embark, and Marginalia packages to give fast and near-comprehensive citation handling. These packages can all be installed using MELPA and GNU ELPA.

Citar

The Citar package (formerly called `Bibtex Actions') by Bruce D'Arcus provides much of the functionality that Org Cite lacks. It provides new processors for insertion, activation, and following, but leaves the export processors unchanged. Its documentation is available from its repository, and there is a short video tutorial available on YouTube. Install Citar (using M-x package-install RET citar RET) and set the appropriate variables by adding the following to your init file.

(setq org-cite-insert-processor 'citar
      org-cite-follow-processor 'citar
      org-cite-activate-processor 'citar
      citar-bibliography Path/To/bibliographyFile)

Citation insertion and editing

You may insert a citation using the command M-x citar-insert-citation (C-c C-x @). This replaces the command M-x org-cite-insert, and has the same keybinding. When you issue this command you will be prompted to search for a reference. To delete an inserted reference, place the cursor over the citation key and use the command M-x citar-org-delete-citation (C-c C-x DEL). To kill an inserted reference, place the cursor over the citation key and use the command M-x citar-org-kill-citation (C-c C-x k). To change an inserted reference, place the cursor over the citation key and use the command M-x citar-insert-citation (C-c C-x @), as with Org Cite itself. To add a citation, place the cursor before or after an existing citation and use the command M-x citar-insert-citation (C-c C-x @). To reorder multiple inserted references, place the cursor over the citation key and use the command M-x citar-org-shift-reference-left (S-LEFT) or M-x citar-org-shift-reference-right (S-RIGHT). To change the citation style, place the cursor before the colon and use the command M-x citar-insert-citation (C-c C-x @). To insert or change a prefix or suffix of a reference, place the cursor over the citation key, prefix or suffix and use the command M-x citar-org-update-pre-suffix (M-p). The prefix needs a space after it and the suffix a space before it.

Even with Citar it is not possible to use citar-insert-citation to specify all arguments allowed by the syntax Kristoffer Balintona has some nice tweaks for Citar in his article `Citations in org-mode: Org-cite and Citar' that go some way to implementing this outstanding functionality. In particular he redefines citar-insert-citation to prompt for a prefix and suffix. However, as far as I can tell there is no way at all to insert or change a common prefix or common suffix with Citar.

Citation following

You may associate files with a reference source entry using BibTex, by setting the fields url, doi, and file (this contating a file path, typically to a PDF of the resource). You may associate notes with a reference by specifying the directory in which they are kept. To do so use M-x set-variable RET citar-notes-paths RET ("Path/To/NotesDir") RET or add the following to your init file.

(setq citar-notes-paths '("Path/To/NotesDir"))

The command M-x org-open-at-point (C-c C-o) will call a list of these resources, which you can navigate using C-n (down) and C-p (up) as usual. Open the chosen resource with RET. If there is no notes file associated with a reference, you will be given the option to create one.

Citation activation

Citar inherits the activation functionality of Org Cite.

Searching references

Even with Citar it is somewhat difficult to interact with a bibliography and the files associated with its entries. To help with this the packages Embark, Vertico, Orderless, and Marginalia are very useful.

Vertico

The Vertico package by Daniel Mendler is a vertical completion user interface. Install Vertico (using M-x package-install RET vertico RET) and ensure vertico-mode is enabled by adding the following to your init file.

(vertico-mode)

With Vertico loaded, the citation insertion command, M-x citar-insert-citation (C-c C-x @) now displays a searchable list of references in the minibuffer, to which your cursor is moved. You may search or navigate this list using C-n (down) and C-p (up) as normal. As before, you may insert single or multiple references.

Orderless

The Orderless package by Omar Antolin Camarena is a completion style that allows searching with any number of space-seperated terms entered in any order. Install Orderless (using M-x package-install RET orderless RET) and set the appropriate variables by adding the following to your init file.

(setq completion-styles '(orderless basic))
(setq completion-category-overrides
      '((file (styles basic partial-completion))))

When entering or replacing a citation with citar-insert-citation (C-u C-x @) you will now be able to search by author, title, date, etc., in any order.

Embark

The Embark package, by Omar Antolin Camarena, provides a contextual menu for a target (in this case, a citation) in the same way right-clicking with a mouse does in software inferior to Emacs. It improves the way in which citations are followed in Citar. To allow Citar to interact with Embark you need the extension package Citar Embark, also by Bruce D'Arcus. Install Embark and Citar Embark (using M-x package-install RET embark RET and M-x package-install RET citar-embark RET) and set the appropriate variables by adding the following to your init file.

(setq citar-at-point-function 'embark-act)
(citar-embark-mode)

This binds the function citar-at-point-function to the function embark-act. Now M-x org-open-at-point (C-c C-o) will open a new window containing a list of available actions.

Marginalia

The Marginalia package, by Daniel Mendler, adds annotations to the minibuffer's completion options. Again, install Embark and Citar Embark (using M-x package-install RET marginalia RET) and ensure marginalia-mode is enabled by adding the following to your init file.

(marginalia-mode)

When typing a Citar command, e.g. the partial command M-x citar-, marginalia will annotate the available completion candidates.

The complete specification

Citation handling according to the specification I have given can be implemented with following Elisp code, which is as it appears in my init file. The packages Helm, Ivy, Helm Bibtex, Ivy Bibtex, and Org Ref are, as the doctors say, contraindicated for this code.

(require 'package)
(setq package-archives '(("melpa" . "https://melpa.org/packages/")
                         ("elpa" . "https://elpa.gnu.org/packages/")))
(package-initialize)

(unless (package-installed-p 'use-package)
  (package-refresh-contents)
  (package-install 'use-package))

(use-package vertico
  :ensure t
  :config
  (vertico-mode))

(use-package orderless
  :ensure t
  :init
  (setq completion-styles '(orderless basic)
        completion-category-overrides
        '((file (styles basic partial-completion)))))

(use-package embark
  :after vertico
  :ensure t)

(use-package marginalia
  :after vertico
  :ensure t
  :config
  (marginalia-mode))

(use-package citeproc
  :ensure t)

(use-package oc
  :init
  (require 'oc-csl)
  (require 'oc-biblatex)
  (require 'oc-natbib)
  (setq org-cite-global-bibliography '("~/Path/To/bibliographyFile")))

(use-package citar
  :ensure t
  :init
  (setq org-cite-insert-processor 'citar
        org-cite-follow-processor 'citar
        org-cite-activate-processor 'citar
        citar-bibliography org-cite-global-bibliography
        citar-notes-paths '("~/Path/To/NotesDir")))

(use-package citar-embark
  :after citar embark
  :ensure t
  :init
  (setq citar-at-point-function 'embark-act)
  :config
  (citar-embark-mode))