An Absolute Beginners Guide to Spacemacs for Academic Writing – Part 2
Part 1 of this guide dealt mainly with installing and configuring Spacemacs.
Now for the academic writing part
If you now have Spacemacs installed and have used org-mode to write some text for an academic paper you will want to be able to enter citations and a bibliography and to be able to convert your org file to various formats like pdf and docx.
My purpose in developing this workflow was to be able to use org-mode in Spacemacs to write academic papers and also be able to export the finished product to Word for the professors to read and comment on. In order to use the open source tools I prefer, that requires going via the open document format used by LibreOffice.
I have experimented a bit and looked at a few other workflows that people have posted and come up with something that works for me. I use Zotero because it is open source, it is very good at grabbing references – and pdfs – off various resources on the web, has a number of powerful features, and has good tools and plug-ins available for working with plain text.
If you prefer to use, say, Docear, BibTeX or Jabref rather than Zotero, if you don’t need to convert to Word, or if you just want to put together your own workflow, there are plenty of posts by good people that can help you with that.
My setup uses all free and open source software and works on Mac OS X, but it should also work on GNU/Linux using the appropriate package manager or apt-get (although some distributions do not come with emacs 24.4 or above as required by Spacemacs – e.g. Trisquel – and some users report issues on Ubuntu. I have had no problems with installation on Linux Mint).
Ideally you will have a few spare GB on your hard drive – This workflow involves installing quite a lot of software. Don’t worry. You’re well on your way to becoming a super-user. If you haven’t already got them you will need to install the items below in the order I have listed them.
Please follow the instructions on the linked pages unless I have included “brew install” instructions.
For my install instructions, enter the text after the $ (command prompt) that I have provided onto the command line of Terminal and press the Enter/Return key (this entering of text and pressing ENTER is often abbreviated to “enter” or just “do”).
Sometimes you will need to wait quite a while for the install process to finish and return you to the command prompt (yourusername $).
Don’t forget that, on a Mac, you can bring up Terminal through Spotlight by
Pressing Command+Space and typing Terminal and pressing the Enter/Return key
Homebrew, by Mark Howell: package manager for Mac OS
$ brew install pandoc
Here is the manual
pandoc-citeproc, by John MacFarlane, Andrea Rossato, for rendering bibliographic reference citations into a variety of styles
To install do
$ brew install pandoc-citeproc
Here is the manual
LibreOffice, by the LibreOffice community: Open source office suite based on the OpenDocument Format – can export to docx, pdf and others
You have a choice of Zotero standalone, or, if using Firefox, Zotero as Add-on. However, although, with the release of Zotero 5 the Add-on version will become obsolete, at present I recommend the Firefox add-on version. On Linux you may wish to follow the instructions as https://www.linuxhelp.com/how-to-install-zotero-in-ubuntu/ You will also want to install the connector for your chosen browser. There is a choice of Firefox, Chrome or Safari.
Zotero Add-ons/Plug-ins (the list is here: https://www.zotero.org/support/plugins – they are also called “extensions” in Firefox ):
The Better Bib(La)TeX add-on, by Emiliano Heyns for drag-and-drop citations and more
zotxt, by Erik Hetzner: Cite items from your Zotero library while writing in plain text
A good comparison of zotxt and Better Bib(La)Tex add-on and set of instructions for installing zotxt is here
The RTF/ODF-Scan for Zotero add-on, by Frank Bennett, Sebastian Karcher: Insert citation markers into any document saved as .odt and convert those into active Zotero citations.
Zotero plug-in for LibreOffice
Zotero Report Customizer by Emiliano Heyns
Recommended: – available in the Firefox Add-ons collection under the Tools menu (hint – scroll down to “see more add-ons!”)
ZotFile, by Joscha Legewie: to automatically rename, move, and attach PDFs (or other files) to Zotero items
and ZoteroQuickLook, by mronkko – reproduces Mac quicklook function for Zotero attachemnts
Have a cup of coffee ..
Using Zotero to build a database of references is documented in their quick start guide
I recommend saving all items to the top-level “My Library” and organizing links to these items in collections and sub-collections
If you use a specific collection for citations in your current paper, you can export that collection for use by pandoc.
This will be your bibliography file for pandoc to work with. Right-click on the collection and select “Export Collection …” Choose Better BibLaTex as your Format and tick only “Keep updated”. Click OK and save the collection with the name of your choice in your folder with the documents you are currently working on. Now you have a “mybibliography.bib” file.
Now you need to set up RTF/ODF-Scan in Zotero. Follow the instructions under “From Zotero Client” at
Now, since you will want to specify the citation style for pandoc to use, you will need the .csl (Citation Style Language) file. For the sake of certainty I copied the style I use into my current documents folder, but Pandoc will check
~/.csl/ by default. Here’s how to do that:
Use the Mac Finder to search for your preferred citation style (mine is apa.csl) in your home folder (Zotero has it there). On my system it can be found at /Users/christopherpoor/Library/Application Support/Firefox/Profiles/nhlkm2qb.default-1455547641581/zotero/styles
Alternatively you can download the styles you want from http://citationstyles.org/styles/ by following their instructions.
Copy and paste the csl file into the folder where the documents you want to convert are stored. This a “quick and dirty” solution. Alternatively, within your pandoc command, you could point to the style saved elsewhere with
Now to convert your org file using pandoc. This can be done simply by using
SPC SPC org-pandoc-export-to-odt
This appears to give the best result as long as your style file is in the same folder as your org file. You can also use pandoc in Terminal or in pandoc-mode within Spacemacs. To do the latter see pandoc layer page and for an explanation of all the options offered by pandoc-mode, see the Pandoc-mode website.
To run pandoc on the Terminal: Open Terminal and use the cd command to navigate to the folder with the document to be converted.
If any of your folder names contain spaces see my Command Line Tips
In pandoc you can use the default ODT reference template.
You need to enter your version of this on one line of the command line
$ pandoc --filter pandoc-citeproc --csl=apa.csl --bibliography=mybibliography.bib myfile.org -o myfile.odt
$ pandoc --filter pandoc-citeproc --csl=/path/to/style-file.csl --bibliography=mybibliography.bib myfile.org -o myfile.odt
if you saved the .csl file elsewhere.
For a full list of possible conversions see the Pandoc documentation.
Then, in Zotero, click on RTF/ODF Scan in the gears/action menu. Select “ODF (to citations)” as file type and select your saved file as the input and your desired output file. Click “Next” and the plugin will convert the citations in your document.
You now have an odt document with live Zotero citations.
You next want to produce a Word document with citations. What I do now is a Zotero “Refresh” by clicking the turning arrows tool in the LibreOffice Zotero toolbar.
This gives two options: Save citations as “Reference Marks” or as “Bookmarks.” I save as “Reference Marks” (this gives me the correct apa format).
Now you can save the document in LibreOffice as docx document. The resulting document can be opened in Word but the citations cannot be edited with Zotero. In any case, I would not recommend editing the document in Word or else you will end up with different versions of the thing you’re still working on.
And footnotes? Org-mode supports footnotes out of the box.
To re-order/re-number your footnotes correctly (the newest one is just added to the top of the footnotes section by default) use
SPC SPC org-footnote-normalize
Copyright © 2016 Christopher J Poor. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
Code in this document is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This document and its code are distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details <http://www.gnu.org/licenses/>.