Citar

[[https://melpa.org/#/citar][file:https://melpa.org/packages/citar-badge.svg]]

• Citar :PROPERTIES: :CUSTOM_ID: citar :END:

• [[#features][Features]]
• [[#installation][Installation]]
• [[#configuration][Configuration]]
• [[#usage][Usage]]
• [[#comparisons][Comparisons]]
• [[#acknowledgements][Acknowledgements]]

** Features :PROPERTIES: :CUSTOM_ID: features :END:

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

• quick filtering and selection of bibliographic entries from the minibuffer, and various commands to run against them.
• a small =citar-embark= companion package, that provides contextual actions in the minibuffer, and also at-point in org, markdown, and LaTeX buffers.
• seamless caching of multiple global and local bibliographic sources
• configurable APIs for:
  • indicatars, that signal the presence of related resources in the minibuffer
  • notes, to integrate with dedicated note packages, with external packages available for =org-roam=, =denote=, and =zk=
  • major-mode adapters
  • entry-opening, to go to the original entry data

Here's a screenshot with [[https://github.com/minad/vertico][vertico]] and symbol customization [[https://github.com/emacs-citar/citar?tab=readme-ov-file#rich-ui][noted below]].

#+caption: vertico with citar [[file:images/vertico.png]]

And here's =citar-capf= in a markdown buffer.

#+caption: completion-at-point in a markdown buffer [[file:images/capf-md.png]]

To see citar in action with org-cite, you can watch [[https://emacsconf.org/2021/talks/research/][this Emacs Conf 2021 presentation]] by [[https://github.com/rka97][Ahmed Khaled]].

** Installation :PROPERTIES: :CUSTOM_ID: installation :END:

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 [[https://github.com/hlissner/doom-emacs/tree/master/modules/tools/biblio][Doom Emacs biblio module]] with the ~vertico~ completion module.
• MELPA :: citar is also available via [[https://melpa.org/#/citar][MELPA]].
• GUIX :: provides the ~emacs-citar~ package.

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

1. [[https://github.com/minad/vertico][Vertico]] (completion interface)
2. [[https://github.com/oantolin/orderless][Orderless]] (completion style)
3. [[https://github.com/oantolin/embark][Embark]] (contextual actions)
4. [[https://github.com/minad/marginalia][Marginalia]] (annotations, and also candidate classification for Embark)

In particular, if you want to narrow your search using authors, titles, etc (i.e., not only citation keys), you need to use a completion style that is order independent; for example, [[https://github.com/oantolin/orderless][Orderless]] with ~completion-styles~ set to ~(orderless basic)~ (see [[https://github.com/oantolin/orderless#overview][example config]]).

We also recommend Emacs 28 or newer.

** Configuration :PROPERTIES: :CUSTOM_ID: configuration :END:

*** Basic :PROPERTIES: :CUSTOM_ID: basic :END:

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.

#+begin_src emacs-lisp (use-package citar :custom (citar-bibliography '("~/bib/references.bib"))) #+end_src

*** =citar-capf=

This package includes a ~completion-at-point~ function to complete citation keys in the buffer, which you can configure like so:

#+begin_src emacs-lisp (use-package citar :custom (citar-bibliography '("~/bib/references.bib")) :hook (LaTeX-mode . citar-capf-setup) (org-mode . citar-capf-setup)) #+end_src

*** 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.

#+begin_src emacs-lisp (use-package citar-embark :after (citar embark) :no-require :config (citar-embark-mode)) #+end_src

*** Org-Cite

This shows the buffer actions made available by =citar-embark=:

#+CAPTION: org-cite at-point integration with =embark-act= [[file:images/org-cite-embark-point.png]]

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

#+begin_src emacs-lisp (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))) #+end_src

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.

You can insert a citation reference with the =citar-insert-reference= command. Alternatively, put the cursor on the citation, and then execute =embark-act=. This pops up a menu: select =r= to put the citation reference in the kill ring. Move the cursor to where you want to insert the reference, then paste from the kill ring.

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

#+begin_src emacs-lisp (setq citar-at-point-function 'embark-act) #+end_src

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 :PROPERTIES: :CUSTOM_ID: major-mode-adapters :END:

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:

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

Citar currently includes the following such adapters:

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

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

*** Opening reference entries

The =citar-open-entry= command will open the source data entry. You may configure this using ~citar-open-entry-function~. By default, this uses ~citar-open-entry-in-file~, which will open the relevant bibliographic file and move point to the entry. The other included option is ~citar-open-entry-in-zotero~, which will select the item in Zotero. Note that functionality depends on [[https://retorque.re/zotero-better-bibtex/][Better BibTeX]] (which you should be using anyway!).

** Rich UI :PROPERTIES: :CUSTOM_ID: rich-ui :END:

There are three sections of the browsing UI.

1. 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.
2. The main display, which by default shows author, title, and date.
3. 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 ~orderless~, even the =:p= or =:n= shorthand).

#+CAPTION: UI sections [[file:images/ui-segments.png]]

*** Templates

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

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

Note:

1. You may include multiple variables in a field; the formatter will print the first one it finds.
2. 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.
3. The asterisk signals to the formatter to use available space for the column.
4. The note template does not take widths, as formatting is inline there rather than columnar.
5. The ~%~ character preceeds a token defined as a key in ~citar-display-transform-functions~, whose value is a list of functions and optional arguments. Note that if you include this, if you also include a width specification, it must come after the width.

*** Indicators

The UI includes configurable indicators. By default, it includes plain text indicators for, each of which indicates the presence of different resources related to the reference:

• notes
• library files
• links
• cited (for references cited in the current buffer)

For other indicators, see the [[https://github.com/emacs-citar/citar/wiki/Indicators][wiki]].

Here's a screenshot using this configuration, which removes the links indicator, and mixes plain text and an icon indicator using ~all-the-icons~.

#+begin_src emacs-lisp (setq citar-indicators (list citar-indicator-files ; plain text citar-indicator-notes-icons))