Citation handling in Emacs

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.

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:

• basic,
• csl (CSL project),
• biblatex (CTAN directory), and
• natbib (CTAN directory).

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.

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.

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.

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.

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.

Citar inherits the activation functionality of Org Cite.

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.

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.

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.

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.