Citar

Features
Installation
Configuration
Usage
Comparisons
Acknowledgements

Features

This package provides a completing-read front-end to browse and act on BibTeX, BibLaTeX, and CSL JSON bibliographic data, and LaTeX, markdown, and org-cite editing support.

When used with vertico, embark, and marginalia, it provides similar functionality to helm-bibtex and ivy-bibtex: quick filtering and selecting of bibliographic entries from the minibuffer, and the option to run different commands against them.

With embark, it also makes available at-point actions in org, markdown, and LaTeX buffers.

Here’s a screenshot with vertico and symbol customization noted below.

To see citar in action with org-cite, you can watch this Emacs Conf 2021 presentation by Ahmed Khaled.

Installation

There are a variety of ways to install citar:

Doom Emacs: The easiest way to install and configure citar and related packages is to use the Doom Emacs biblio module with the vertico completion module.
MELPA: citar is also available via MELPA.
GUIX: provides the emacs-citar package.

In addition, the following packages are strongly recommended for the best experience.

Vertico (completion interface)
Orderless (completion style)
Embark (contextual actions)
Marginalia (annotations, and also candidate classification for Embark)

We also recommend Emacs 28, as this package relies on two of its features, that greatly enhance the UI.

Configuration

Basic

This is the minimal configuration, and will work with any completing-read compliant vertical completion UI, like Vertico, or the built-in icomplete-vertical, with actions available via M-x commands.

(use-package citar
  :bind (("C-c b" . citar-insert-citation)
         :map minibuffer-local-map
         ("M-b" . citar-insert-preset))
  :custom
  (citar-bibliography '("~/bib/references.bib")))

Embark

The citar-embark package adds contextual access actions in the minibuffer and at-point via the citar-embark-mode minor mode.

When using Embark, the Citar actions are generic, and work the same across org, markdown, and latex modes.

(use-package citar-embark
  :after citar embark
  :no-require
  :config (citar-embark-mode))

Org-Cite

If you want to use Citar only in Org-Mode, this is the best option.

(use-package citar
  :no-require
  :custom
  (org-cite-global-bibliography '("~/bib/references.bib"))
  (org-cite-insert-processor 'citar)
  (org-cite-follow-processor 'citar)
  (org-cite-activate-processor 'citar)
  (citar-bibliography org-cite-global-bibliography)
  ;; optional: org-cite-insert is also bound to C-c C-x C-@
  :bind
  (:map org-mode-map :package org ("C-c b" . #'org-cite-insert)))

You can insert citations with the org-cite-insert command, which is bound to C-c C-x C-@ in Org-Mode buffers. The optional :bind command above also gives it the shorter C-c b binding.

If you prefer to have the Embark menu open with org-open-at-point, you should set this variable.

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

You can invoke both embark-act and embark-dwim, however, independently of org-at-point, and in other modes such as latex-mode.

Major-mode adapters

Citar includes an adapter framework to enable major-mode specific editing integration. Such adapters can provide the following capabilities, which one can configure with the citar-major-mode-functions alist:

insert-keys: to insert citation keys (this may go away though)
insert-citation: to insert citations
insert-edit: to insert citations or edit at point
local-bib-files: to find bibliographic files associated with a buffer
key-at-point: returns the citation key at point
citation-at-point: returns the list of keys in the citation at point

Citar currently includes the following such adapters:

citar-org: by default, only supports org-cite, but can one can configure for other formats
citar-latex: configurable bibtex, natbib and biblatex support (requires AUCTeX)
citar-markdown: by default, only supports the pandoc citation syntax

None of these should require any configuration, and should load as needed.

Rich UI

There are three sections of the browsing UI.

The prefix, exploiting the affixation feature only available starting with Emacs 28, and holding the symbols to indicate the presence of PDFs or notes associated with the entries.
The main display, which by default shows author, title, and date.
The suffix, which by default shows citekey, reference type, and (if present) tags or keywords.

You can search against all of the above content. For the prefix, you can filter for associated files or notes using has:file or has:notes respectively (and at least with my setup, even the :p or :n shorthand).

Templates

The citar-templates variable configures formatting for these sections, as well as the default note function. Here’s the default value:

(setq citar-templates
      '((main . "${author editor:30}     ${date year issued:4}     ${title:48}")
        (suffix . "          ${=key= id:15}    ${=type=:12}    ${tags keywords:*}")
        (preview . "${author editor} (${year issued date}) ${title}, ${journal journaltitle publisher container-title collection-title}.\n")
        (note . "Notes on ${author editor}, ${title}")))

Note:

You may include multiple variables in a field; the formatter will print the first one it finds.
If you plan to use CSL JSON at all, you can and should include CSL JSON variables names where appropriate as such options. The default main template dates field demonstrates this.
The asterisk signals to the formatter to use available space for the column.
The note template does not take widths, as formatting is inline there rather than columnar.

Icons

By default, this UI is plain text, but you can configure it to use icons instead. Here’s how to configure it to use all-the-icons as in the screenshot at the top:

(setq citar-symbols
      `((file ,(all-the-icons-faicon "file-o" :face 'all-the-icons-green :v-adjust -0.1) . " ")
        (note ,(all-the-icons-material "speaker_notes" :face 'all-the-icons-blue :v-adjust -0.3) . " ")
        (link ,(all-the-icons-octicon "link" :face 'all-the-icons-orange :v-adjust 0.01) . " ")))
(setq citar-symbol-separator "  ")

Test Script

The repository test directory also includes a script you can use to run this and associated packages in the emacs -Q sandbox. To do that, simply run ./run.sh from the test directory. By default, this will use selectrum as the completion system. If you would like to try vertico instead, just do M-x vertico-mode.

History and predefined searches

citar has functionality similar to the predefined search functionality in helm-bibtex and ivy-bibtex, but with a different implementation. Rather than create a new command with the search terms as argument, you just set the citar-presets variable, and add the strings you want to access:

(setq citar-presets '("one search string" "another search string"))

You then have two ways to access these strings from the completion prompt:

by using M-n from the prompt, which will cycle through the strings
by calling citar-insert-preset with a keybinding, and then selecting the string

citar also preserves the history of your selections (see caveat below about multiple candidate selection though), which are also accessible in your completion UI, but by using M-p. You can save this history across sessions by adding citar-history to savehist-additional-variables.

Refreshing the library display

Citar uses a cache to speed up library display. If a bib file changes, the cache will automatically update the next time you run a Citar command.

Note that cached data preformatted completion candidates are independently tracked by file. So, for example, if you have one very large bibliography file that changes a lot, you might consider splitting into one large file that is more stable, and one-or-more smaller ones that change more frequently.

Notes

Citar offers configurable note-taking and access integration. The citar-notes-sources variable configures note backends, and citar-notes-source activates your chosen backend.

A backend primarily specifies functions to update the Citar display, to create the completion candidates, and to open existing and new notes. See the citar-notes-sources docstring for details, and the citar-register-notes-source and citar-remove-notes-source convenience functions.

Files, file association and file-field parsing

If you have citar-library-paths set, the relevant open commands will look in those directories for file names of CITEKEY.EXTENSION. They will also parse contents of a file-field. The citar-file-parser-functions variable governs which parsers to use, and there are two included parsers:

The default citar-file-parser-default parser works for simple colon or semi-colon-delimited lists of file paths, as in Zotero.
The citar-file-parser-triplet works for Mendeley and Calibre, which represent files using a format like :/path/file.pdf:PDF.

If you have a mix of entries created with Zotero and Calibre, you can set it like so and it will parse both:

(setq citar-file-parser-functions
  '(citar-file-parser-default
    citar-file-parser-triplet))

The citar-library-file-extensions variable governs which file extensions the open commands will recognize; when `nil`, it will recognize all extensions. The citar-file-additional-files-separator variable defines what patterns citar should identify for multiple library files for the same reference key. Here’s an example to only recognize pdf and jpg extensions, but additional file names of the form test-1.jpg:

(setq citar-library-file-extensions (list "pdf" "jpg")
      citar-file-additional-files-separator "-")

To change how citar opens files with given extensions, customize the citar-file-open-functions variable defined in citar-file.el.

When used with embark and consult, you will have a range of alternate actions available for the candidates.

BibTeX Crossref File Support

For BibTeX entries that have a ‘crossref’ field, Citar will associate the entry’s key with the resources (files, notes, links) that are associated with the cross-referenced entry.

For example: consider an entry for “Baym1965” that has a ‘crossref’ field “Meyers1999”. When citar-open is called and “Baym1965” is selected, the minibuffer will list all files, notes, and links associated with both “Baym1965” and “Meyers1999”. The proper prefixes, denoting an associated file, note, or link, will also be listed with each candidate in the minibuffer.

NOTE: For the BibTeX crossref feature to work properly, the entry with the ‘crossref’ field must come before the cross-referenced entry in the bib file. (This is a requirement of BibTeX, not of Citar specifically.) In the example above, then, the entry for “Baym1965” must come before the entry for “Meyers1999”.

Usage

You have a few different ways to use citar.

Org-cite

Citar includes an org-cite citar processor, with “insert,” “activate” and “follow” capabilities.

The “insert processor” uses citar-select-refs to browse your library to insert and edit citations and citation references using the org-cite-insert command. The command is context-aware, so depending on where point is in the buffer, will behave differently. For example, if point:

precedes the colon, you will be prompted to edit the style
is on an existing citation-reference, you will be prompted to replace it
follows or precedes a citation-reference, you will be prompted to add a new citation-reference

The “activate processor” runs the list of functions in citar-org-activation-functions, which by default is the basic processor from oc-basic to provide fontification, and also a little function that adds a keymap for editing citations at point. That keymap includes the following bindings that provide additional citation and citation-reference editing options.

key	binding
C-c C-x DEL	oc-citar-delete-citation
C-c C-x k	oc-citar-kill-citation
S-<left>	oc-citar-shift-reference-left
S-<right>	oc-citar-shift-reference-right
M-p	oc-citar-update-pre-suffix
<mouse-1>	citar-dwim
<mouse-3>	embark-act

The “follow processor” provides at-point functionality accessible via the org-open-at-point command. By default, in org-mode with org-cite support, when point is on a citation or citation-reference, and you invoke org-open-at-point, it will run the default command, which is citar-open. Changing this value to embark-act with embark installed and configured will provide access to the standard citar commands at point.

Org-cite citations include optional “styles” and “variants” to locally modify the citation rendering. When inserting a new citation, calling org-cite-insert with a prefix arg will prompt to select a style. To edit an existing citation’s style, just make sure point is on the citation prefix before running org-cite-insert, and you will get a list of available styles. That list is based on your configuration; if you have the oc-natbib and oc-csl processors configured, for example, the list will include the styles and variants available in those two processors. The variants included in the bundled processors include the following, with the shortcuts in parentheses:

bare (b): without surrounding punctuation
caps (c): force initial capitalization
full (f): ignore et al shortening for author names

Generally, you shouldn’t need these, but they can be useful in certain circumstances. If an export processor doesn’t support a specific variant for a specific style, it should just fallback to the base style. For example, if you specify text/f, and the export processor you use doesn’t support the f variant there, it should just output as if you specified text.

`M-x`

Simply do M-x and select the command that you want, enter the terms to find the item you are looking for, and hit return. This runs the default action: the command you invoked.

Access an alternate action via `embark-act`

If while browsing you instead would rather edit that record, and you have embark installed and configured, this is where embark-act comes in. Simply input the keybinding for embark-act (in my case C-o), and select the alternate action.

Use `embark-collect-snapshot`

A final option, that can be useful: run embark-collect-snapshot (S) from embark-act. This will select the candidate subset, and open it in a separate buffer. From there, you can run the same options discussed above using embark-act (which is also bound to a in the collect buffer).

So, for example, say you are working on a paper. You hold the complete super-set of items you are interested in citing at some point in that buffer. From there, you can run different actions on the candidates at will, rather than search individually for each item you want to cite.

Use `citar-dwim`

M-x citar-dwim will run the default action on citation keys found at point directly. If you have embark installed, you use can embark-dwim instead for the same behavior, and embark-act for additional actions at-point.

If no citation key is found, the minibuffer will open for selection. You can disable this behavior by setting citar-at-point-fallback to nil.

Related Packages

The following packages extend or otherwise enhance citar.

Notes Sources

These small packages provide citar notes sources, and so tighter integration with the respective notes management packages.

Comparisons

To understand how citar compares to other packages like org-ref, ivy-bibtex and helm-bibtex (and the related bibtex-completion), see the comparisons page on the wiki.

Acknowledgements

The ideas in this project were initially worked out in a conversation with Maxime Tréca and Daniel Mendler. Daniel, author of consult and marginalia, helped us understand the possibilities of the new suite of completing-read packages, while Maxime came up with an initial prototype.

This code takes those ideas and re-implements them to fill out the feature set, and also optimize the code clarity and performance.

tivp/citar