org-ref: citations, cross-references, indexes, glossaries and bibtex utilities for org-mode

Overview of org-ref for export to PDF via LaTeX.

About org-ref

org-ref makes it easy to insert citations, cross-references, indexes and glossaries as hyper-functional links into org files. The links are fontified so you can tell them apart from other links, and each link is clickable to access functions like opening a pdf, notes or url associated with the link. Each link also can be exported to LaTeX to build a PDF. For citations, export to other formats is supported by citeproc for high quality export to HTML, markdown, plain text, or stand-alone (i.e. independent of a bibtex file) LaTeX. For a full explanation of the features in org-ref see ./org-ref.org.

Breaking changes in version 3

Version 3 supports the original org-ref link-syntax, so all your legacy documents should still work as expected. Version 3 defaults to the new syntax, so new documents will have the newer style links in them.

Version 3 introduces several breaking (or at least, you will have to update some *Configuration to get it working again) changes for users with heavily customized org-ref version 2 setups. These are described below.

Why the breaking changes? The main reason is to fully support a richer citation syntax that allows pre/postnotes on citations, and to integrate the use of CSL for non-LaTeX exports. Additionally, org-ref was in need of refactoring and improvements. org-ref is at least 7 years old, and has accumulated a lot of features in that time. I have been wanting to consolidate and clean up the code for a while, and the new syntax provided an opportunity for that.

I have also taken this opportunity to introduce some new libraries like ./org-ref-refproc.el which is an analog of citeproc for cross-references in non-LaTeX exports.

If you are happy with your version 2 setup, you can keep it, and the version 2 branch exists (https://github.com/jkitchin/org-ref/tree/org-ref-2) and there is a stable v2.0 in MELPA-Stable. I do not plan to develop version 2 further.

[2021-10-18 Mon] Short list of the main breaking changes

• Version 3 no longer uses many org-ref-* variables. See *Configuration for details.
• All completion candidates are generated by bibtex-completion
• There are only two backends - helm-bibtex and ivy-bibtex, and both rely on bibtex-completion
  • Neither helm nor ivy is automatically installed
  • The other backends have been removed
• Making/opening notes, opening PDFs are all handled by bibtex-completion functions
• Almost all of the non-LaTeX export is handled by citeproc-el now (the tooltips are generated by bibtex-completion).
  • The older org-ref citeproc has been removed
• Drag-and-drop code is gone
• legacy code supporting org-mode version 8 is gone

What about org-cite?

A new syntax for citations was added in org-mode version 9.5. This library is similar to org-ref, in the sense that it provides a mechanism to add citations to org-files, but it has a different approach. org-cite is designed to be very modular, with different processors for inserting, activating, following and exporting citations. It also uses a different cite/style type of syntax. It does not handle cross-references or provide any of the bibtex tools that are available in org-ref. The main advantages of org-cite include:

1. It is built in to org-mode now
2. It is highly modular, so you can configure it any way you want

org-cite does not meet my citation and technical document publishing needs, and it was not possible to integrate it into org-ref without compromising those. I decided to continue developing org-ref for that reason. org-ref now provides the same citation capabilities as org-cite does as far as I know. I plan to continue using org-ref for my technical document writing activities.

You can use both org-cite and org-ref (although you should not do that in the same document as they are independent citation tools).

Screenshots

Here are some annotated images of basic insertion of citations in org-mode. These are with the ivy backend.

This what an inserted link looks like.

The links in org-ref are hyper-functional (that means they have more than one action associated with them). They do things when your cursor is on them, or you click on them, and when the mouse hovers over them.

Here is an example of a menu of actions you get when you click on a cite link.

Here is a cross-reference link.

org-ref can analyze your org-file and tell you about it, for example if there are bad citations, multiply defined labels, bad reference links, missing bibliography files, etc… You can select each one and it will jump to the location to help you fix it.

Installation

Package installation via Melpa

org-ref has been added to Melpa. This is the recommended way to install org-ref as it should also install almost all the dependencies. It also should reflect what is in the master branch in the Github repo (https://github.com/jkitchin/org-ref).

(add-to-list 'package-archives
	     '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

Then, you should be able to do M-x package-list-packages, find org-ref and install it, or with

(use-package org-ref)

Two exceptions to packages that are not installed are helm, helm-bibtex, ivy and ivy-bibtex. You have to install those yourself. This change is to accommodate people who just can not stand having those packages installed if they do not use them.

Installation via github

Make sure all the dependencies are installed. Then clone this repo, add it to your load-path.

git clone https://github.com/jkitchin/org-ref.git

Add this to your .emacs file and see the *Configuration section.

Configuration

Version 3 has eliminated all the org-ref-* variables, and instead uses analogous variables defined in bibtex-completion.

There are some working configurations at https://github.com/jkitchin/org-ref/tree/master/melpa.

Here is how I have these variables set for myself.

(setq bibtex-completion-bibliography '("~/Dropbox/emacs/bibliography/references.bib"
					 "~/Dropbox/emacs/bibliography/dei.bib"
					 "~/Dropbox/emacs/bibliography/master.bib"
					 "~/Dropbox/emacs/bibliography/archive.bib")
	bibtex-completion-library-path '("~/Dropbox/emacs/bibliography/bibtex-pdfs/")
	bibtex-completion-notes-path "~/Dropbox/emacs/bibliography/notes/"
	bibtex-completion-notes-template-multiple-files "* ${author-or-editor}, ${title}, ${journal}, (${year}) :${=type=}: \n\nSee [[cite:&${=key=}]]\n"

	bibtex-completion-additional-search-fields '(keywords)
	bibtex-completion-display-formats
	'((article       . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*} ${journal:40}")
	  (inbook        . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*} Chapter ${chapter:32}")
	  (incollection  . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*} ${booktitle:40}")
	  (inproceedings . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*} ${booktitle:40}")
	  (t             . "${=has-pdf=:1}${=has-note=:1} ${year:4} ${author:36} ${title:*}"))
	bibtex-completion-pdf-open-function
	(lambda (fpath)
	  (call-process "open" nil 0 nil fpath)))

I also find these settings helpful for automatically generating bibtex keys.

(require 'bibtex)

(setq bibtex-autokey-year-length 4
	bibtex-autokey-name-year-separator "-"
	bibtex-autokey-year-title-separator "-"
	bibtex-autokey-titleword-separator "-"
	bibtex-autokey-titlewords 2
	bibtex-autokey-titlewords-stretch 1
	bibtex-autokey-titleword-length 5
	org-ref-bibtex-hydra-key-binding (kbd "H-b"))

(define-key bibtex-mode-map (kbd "H-b") 'org-ref-bibtex-hydra/body)

After you set those options, you have these options to load org-ref.

If you prefer ivy-bibtex, you should use this. It requires ivy-bibtex, but this is not currently automatically installed by MELPA.

(require 'org-ref-ivy)

(setq org-ref-insert-link-function 'org-ref-insert-link-hydra/body
      org-ref-insert-cite-function 'org-ref-cite-insert-ivy
      org-ref-insert-label-function 'org-ref-insert-label-link
      org-ref-insert-ref-function 'org-ref-insert-ref-link
      org-ref-cite-onclick-function (lambda (_) (org-ref-citation-hydra/body)))

If you prefer helm, you can instead use this. This uses code from helm-bibtex for citation insertion. It requires helm-bibtex, but this is not currently automatically installed by MELPA.

(require 'org-ref-helm)
(setq org-ref-insert-link-function 'org-ref-insert-link-hydra/body
      org-ref-insert-cite-function 'org-ref-cite-insert-helm
      org-ref-insert-label-function 'org-ref-insert-label-link
      org-ref-insert-ref-function 'org-ref-insert-ref-link
      org-ref-cite-onclick-function (lambda (_) (org-ref-citation-hydra/body)))

org-ref no longer binds keyboard shortcuts for you. You have some options here. To get the behavior of version 2, use this in your init file:

(define-key org-mode-map (kbd "C-c ]") 'org-ref-insert-link)

C-c ]

insert a citation

C-u C-c ]

insert a cross-reference

Cu C-u C-c ]

insert a label

or

(define-key org-mode-map (kbd "C-c ]") 'org-ref-insert-link-hydra)

C-c ] c

insert a citation

C-c ] r

insert a cross-reference

C-c ] l

insert a label

You can bind each insert command separately if you want after the library is loaded like this. Here I use the hyper key as a modifier, but you can choose anything you find convenient.

(define-key org-mode-map (kbd "H-c") org-ref-insert-cite-function)
(define-key org-mode-map (kbd "H-r") org-ref-insert-ref-function)
(define-key org-mode-map (kbd "H-l") org-ref-insert-label-function)

If you use some other completing-read backend like selectrum, or ido, then for a bare-bones library that uses vanilla completing-read, you can simply require ‘org-ref. I don’t find the vanilla completing-read setup that useful on its own as it doesn’t do candidate narrowing or fuzzy matching without some external configuration. It is an option if you want it though.

(require 'org-ref)

You can use any other library that inserts links you want. Some of these include:

1. bibtex-actions (https://github.com/bdarcus/bibtex-actions#configuration)
2. ebib (https://joostkremers.github.io/ebib/)
3. You could even roll your own insert functions.

LaTeX/PDF export

If you plan to build PDF files via LaTeX you need to make sure that org-latex-pdf-process is set to process the bibliography (using bibtex or biblatex). Here is one example of how to do that (see ./org-ref.org::*LaTeX export for other alternatives).

(setq org-latex-pdf-process (list "latexmk -shell-escape -bibtex -f -pdf %f"))

Go forth and citate.

Some other useful libraries in org-ref

Note many of these have been renamed with an org-ref prefix.

doi-utils

Download bibtex entries and PDFs from doi and crossref queries.

org-ref-pdf

Add drag-n-drop PDF to create bibtex entries

org-ref-url-utils

Add drag-n-drop urls to create bibtex entries

org-ref-bibtex

Utility functions for bibtex

org-ref-arxiv

arxiv links, add bibtex entries from arxiv.org.

org-ref-pubmed

pubmed links, add bibtex entries from PMID.

org-ref-isbn

Add bibtex entries from a book ISBN

org-ref-wos

WebOfKnowledge links and queries

org-ref-scopus

Scopus links and queries

x2bib

Convert bibliography formats to and from bibtex

nist-webbook

Links to NIST Webbook resources

org-ref-scifinder

one small function for searching SciFinder

org-ref-worldcat

One small function for searching Worldcat

Manual

For more information, see the org-ref manual, or preferably use M-x org-ref-help in emacs.

Errors and issues

Please report errors here: issues.

Contributors

I would like to thank the contributors to org-ref, and everyone who has filed an issue, or asked about org-ref on the org-mode Mailing list.

If you are interested in making a contribution to org-ref, I encourage you to reach out to me to discuss the idea first. The issue handler is a great way to do that, so that others can offer opinions too.