Using org-ref for citations and references
Posted May 13, 2014 at 11:25 AM | categories: org-mode, emacs | tags:
Updated November 15, 2014 at 03:12 PM
Table of Contents
org-ref is an emacs-lisp module to handle bibliographic citations, and references to figures, tables and sections in org-mode. It was written first for use in org-mode, and for reasonable export to LaTeX. It does not work well for any other export (eg HTML) for now. The goal of org-ref is to make it easy to add citations, and that the citations be useful, clickable links. Below, I illustrate some of those features.
1 Installation
You can get the source here: https://github.com/jkitchin/jmax/blob/master/org-ref.org . This is an org-mode file, and you can load it with
(org-babel-load-file "org-ref.org")
That should be all you need for basic usage.
2 Basic usage for citations
org-ref was written with bibtex in mind. We will discuss customization to use biblatex later.
The first thing you should do is add a bibliography link to your document. This link is usually put at the end of the document, where you want the bibliography to be printed in a LaTeX export. Use the filename of the bibliography with its extension in the link, and you can use multiple files if they are separated by commas. The bibliography link is clickable, and it will open the bibliography that you clicked on. Depending on the LaTeX class you are exporting to, you may also need to set a bibliographystyle.
Out of the box, org-ref binds the key "C-c ]" to insert a citation. That key runs the command org-ref-insert-cite-link, which will prompt you for a regular expression to search your bibliographies for. The search is done using reftex, so you can mark several entries at once, and they will be added as a citation link. The actual kind of link used is dependent on the value of org-ref-default-citation-link, which defaults to cite.
If your cursor is on a citation link, or at the end of the link, you can run the command again to append new citations to the link. The new entries are separated by commas. The links are clickable, and when you click on them you will see a message in the minibuffer with the citation, and options to open the entry, open a pdf (if you have it), open the url (if the entry has one), or to open notes about the entry. You get this menu for the entry that you clicked on.
If you want a different type of citation, type C-u C-c ]. You will be prompted for a format, and you can choose a different type of link format. Most bibtex formats are supported, and some biblatex formats are supported.
3 Basic usage for references
The other use of org-ref is for references to labels in your document. You can put labels in figure and table captions, and then reference them in your document. The label link is clickable, and when you click on it there will be a message in the minibuffer telling you how many labels of that name were found (it should be one).
| 0 | 3 |
| 4 | 7 |
You can then refer to Table (tab-boring). The ref links are also clickable, and they take you to the spot where the label is defined. You can enter ref links with completion. Press C-c C-l, type ref, press enter, and then press tab. You will get a list of the labels defined in the buffer you can choose from. There are many things you can make a ref to including a tblname, a label link, an explicit \label{}, and an org-mode #+label: line. (tab-boring)
There is an eqref link that is used for equations. You must use LaTeX labels in the equation for this.
\[e^x = 4 \label{eq-exp} \]
You can see in (
4 Miscellaneous links
There are two link types for generating a LateX list of tables and list of figures. These links are clickable, and they open a temporary buffer with a list of the tables or figures that you can click on. They export to \listoftables and \listoffigures
You can run these as commands, org-ref-list-of-tables and org-ref-list-of-figures if you do not want a list of those things in your exported document.
5 Customization
5.1 Default bibliography, pdf directory,
This is an optional configuration, but it is handy to define a default bibliography so that you can add citations to an org-file without defining a bibliography link. I store all pdfs of bibtex entries in the directory defined by org-ref-pdf-directory, and by the name of the bibtex entry label. This enables org-ref to open the pdf if it can find it. The notes file is optional, I create org-entries for each bibtex entry, which I have experimented with various ways of organizing them with tags, and in topical headings.
(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/")
5.2 New key binding
The default key binding to insert a citation is C-c ]. I chose that because I do not like pressing shift to get ). However, this key binding usurps an org-mode agenda file command. To change this, set this variable
(setq org-ref-insert-cite-key "C-c )")
- You may have to restart emacs to get C-c ] back.
5.3 Default link type
If you use another citation type alot, you may change the default link type. For example, you may prefer autocite links by default. Just set it like this:
(setq org-ref-default-citation-link "autocite")
5.4 New citation types
There are so many citation types between bibtex and biblatex. I did not try to add them all. You can add new citation links yourself in your init file. Here, we add a new cite link called citez, and assign a reftex menu key of z to it. This function automatically adds the new link to org-mode, with the citation menu functionality, creates the completion function, and adds the citation to the list of known types.
(org-ref-define-citation-link "citez" ?z)
(org-ref-define-citation-link "citeauthorfull" ?F) citeauthorfull:hautier-2012-accur
It is assumed that this will be exported as \citez[optional stuff]{label}. If you need more flexibility than that, you will have to define everything manually.
For example, the original cite link was defined like this.
(defun org-ref-cite-link-format (keyword desc format) (cond ((eq format 'html) (format "(<cite>%s</cite>)" path)) ((eq format 'latex) (concat "\\cite" (when desc (format "[%s]" desc)) "{" (mapconcat (lambda (key) key) (org-ref-split-and-strip-string keyword) ",") "}")))) (org-add-link-type "cite" 'org-ref-cite-onclick-minibuffer-menu ;; clicking function 'org-ref-cite-link-format) ;; formatting function
You should also add your new citation type to the list of org-ref-cite-types.
6 Summary
This covers most of the basic org-ref functionality. There are also several utility functions for interacting with org-buffers and bibtex files that will be described later.
See http://screencast.com/t/bxfafVydE for a screencast of using org-ref.
Copyright (C) 2014 by John Kitchin. See the License for information about copying.
Org-mode version = 8.2.7c