I have started using Org mode in Emacs to do most of my writing. After about a year of using it to take notes, write blog posts, create presentations and do most things that involve writing, I finally started figuring out how to use it to write academic papers. The one missing element in my workflow was citations. org-ref is a package that could be used to generate citations, bibliographies and cross-references to tables and figures in a document written using Emacs org mode. It took me several hours to get the system working and so I have written down the instructions that worked for me in this post.
1 What you can do with org-ref
A quick video tutorial on the capabilities of org-ref can be found on YouTube.
2 Installation instructions
You can install org-ref from Melpa. For configuration instructions, go here.
3 Associating your paper with the bibliography file
Before you start including citations in your org file, you have to tell org mode where your bibliography file is. You can do this by typing: “bibliography : your-file-name (without spaces) at the end of the document.
4 Including citations in the org file
You can use the sub-menu for ‘org-ref’ under ‘org’ menu item on top or the keyboard shortcut “C-c ]” to start inserting citations. This will open the interface for selecting one or more citations that need to be inserted.
To select a citation, just typing the author name, title or anything else that will narrow your search. Once the paper of interest is highlighted, you can press enter to cite it.
For multiple citations do the same as above, but once the article is highlighted, press ctrl+space to select it, rather than pressing Enter. After you select all articles of interest, you can press enter to insert citation.
If you put your cursor over the citation link you will be able to see the full citation in the mini-buffer.
5 Bibliography style
You can mention the bibliography style that you want by typing bibliographystyle : style-you-want (without spaces) at the bottom of the document, where you want the bibliography placed.
6 Generating bibliography
When you are ready to share the work with others, you can export the org file into html, pdf or other formats with well formatted citations. I was able to export to html without any problem. With PDF, I kept getting error messages about unknown citations. If you get the error message, here is the work around.
7 Undefined citation error
The undefined citation error is created by Latex. You could learn more about why that happens in an article by Andrew Roberts on creating bibliographies with Latex. Here is a quick summary of what I do to get a beautiful pdf file:
Note: I use Linux Mint with pdfLatex
- Export org document to a Latex file. This will create a tex file called your-file-name.tex
- Open shell in emacs and execute the following commands one by one (or you could go to terminal and go to the directory with your org file).
- Execute command: pdflatex your-file-name.tex
- Execute command: bibtex your-file-name. aux (without space)
- Execute command: pdflatex your-file-name.tex
- Execute command: pdflatex your-file-name.tex
That process produced the pdf document that I wanted with the name your-file-name.pdf.