Overview of org-ref for export to PDF via LaTeX.
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.
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.
- 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
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:
- It is built in to org-mode now
- 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).
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.
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.
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.gitAdd this to your .emacs file and see the *Configuration section.
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:
- bibtex-actions (https://github.com/bdarcus/bibtex-actions#configuration)
- ebib (https://joostkremers.github.io/ebib/)
- You could even roll your own insert functions.
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.
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
For more information, see the org-ref manual, or preferably use M-x org-ref-help in emacs.
Please report errors here: issues.
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.