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

Table of Contents

• Screenshots
• Installation
  • Package installation via Melpa
  • Installation via github
  • Configuration
    • Org-ref and citation managers
• Some other useful libraries in org-ref
• Manual
• Errors and issues
• Contributors

Screenshots

Here are some annotated images of basic insertion of citations in org-mode.

The links in org-ref are functional. They do things when your cursor is on them, or you click on them, and sometimes when the mouse hovers over them.

Here is an example of a menu of actions you get when you click on a cite 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 will also install all the dependencies.

(add-to-list 'package-archives
	     '("melpa" . "http://melpa.org/packages/") t)
(when (< emacs-major-version 24)
  ;; For compatibility
  (add-to-list 'package-archives '("gnu" . "http://elpa.gnu.org/packages/")))
(package-initialize)

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

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

(require 'org-ref)

Configuration

You should set these variables. Here is an example of how mine are set in an init.el file.

(setq reftex-default-bibliography '("~/Dropbox/bibliography/references.bib"))

;; see org-ref for use of these variables
(setq org-ref-bibliography-notes "~/Dropbox/bibliography/notes.org"
      org-ref-default-bibliography '("~/Dropbox/bibliography/references.bib")
      org-ref-pdf-directory "~/Dropbox/bibliography/bibtex-pdfs/")

You may want to set some convenient keys for working in your bibtex file. These commands operate on the citation key at point.

If you use helm-bibtex as the citation key completion method you should set these variables too.

(setq bibtex-completion-bibliography "~/Dropbox/bibliography/references.bib"
      bibtex-completion-library-path "~/Dropbox/bibliography/bibtex-pdfs"
      bibtex-completion-notes-path "~/Dropbox/bibliography/helm-bibtex-notes")

;; open pdf with system pdf viewer (works on mac)
(setq bibtex-completion-pdf-open-function
  (lambda (fpath)
    (start-process "open" "*open*" "open" fpath)))

;; alternative
;; (setq bibtex-completion-pdf-open-function 'org-open-file)

There are alternative citation key completion methods.

org-ref-helm-cite

An alternative to helm-bibtex

org-ref-ivy-cite

Uses ivy for key completion

org-ref-reftex

Uses reftex and org-mode for completion (no longer developed)

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"))

Finally, add this to your init.el files.

(require 'org-ref)

Org-ref and citation managers

If you are using a Bibtex file exported from some citation manager then additionally set the variable org-ref-get-pdf-filename-function to the appropriate value (see docstring for possible values).

The following table shows correct settings for various citation managers:

Please update the table or open an issue to add values for other citation managers. For more info about org-ref and citation managers consult the org-ref manual.

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-latex

org-ref-like features in LaTeX.

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
• org-ref-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.