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.

What about org-cite?

A new syntax for citations was added in org-mode version 9.5. 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:

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

It is possible to use org-cite for citation support instead of the org-ref citation links. You can configure the org-ref-insert-cite-function variable to use org-cite-insert. This will then use your org-cite configured processors to insert, follow, activate and export citations. You should avoid mixing org-ref citation links and org-cite citations. They are handled independently.

(setq org-ref-insert-cite-function
      (lambda ()
	(org-cite-insert nil)))

You can still use the org-ref cross-reference links if you use org-cite citations. These packages should be able to co-exist without issue.

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)

(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)
(require 'org-ref-ivy)

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)
(require 'org-ref-helm)

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
C-u C-u C-c ]: insert a label

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

C-c ] [:: insert a citation

C-c ] ]: insert a cross-reference
C-c ] \: 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:

citar (https://github.com/bdarcus/citar#configuration)
ebib (https://joostkremers.github.io/ebib/)
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.

x2bib: Convert bibliography formats to and from bibtex. In most cases, it relies on the command line bibutils package (available in source form at the link; can be installed on a Mac using Homebrew with brew install bibutils.

The following libraries are not loaded by default. They may be useful in specialist cases:

doi-utils: Download bibtex entries and PDFs from doi and crossref queries.
nist-webbook: Links to NIST Webbook resources
org-ref-arxiv: arxiv links, add bibtex entries from arxiv.org.
org-ref-bibtex: Utility functions for bibtex
org-ref-isbn: Add bibtex entries from a book ISBN
org-ref-pubmed: pubmed links, add bibtex entries from PMID.
org-ref-scifinder: one small function for searching SciFinder
org-ref-scopus: Scopus links and queries
org-ref-worldcat: One small function for searching Worldcat
org-ref-wos: WebOfKnowledge links and queries

The following libraries are still included, but they have been unreliable and are no longer recommended for use:

org-ref-pdf: Add drag-n-drop PDF to create bibtex entries (this code has not been reliable, and is no longer recommended for use)
org-ref-url-utils: Add drag-n-drop urls to create bibtex entries

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.