Working with references in Markdown: a better way
15 June 2018
This is a revised version of a post I wrote for History to the Public back in May 2015. You can have a read of the original here, if you’re interested. I’ve edited the wording slightly in parts, to make it sound more like a human wrote it, but otherwise it’s more or less unchanged…
In the tutorial included with my previous post on Markdown, I mentioned that accurate referencing is one of the few areas in which Markdown struggles to compete with more feature-rich word processors as an academic writing tool. Markdown does include its own citation syntax, which functions in a rudimentary way. However, in my experience, this syntax causes too many problems to serve as the basis for any long-term referencing method. In particular, it works poorly with the citation keys used by certain reference managers, and tends to generate citations with incorrect or inconsistent capitalization. In an otherwise ideal system, it’s something of a blemish.
Zotero: the missing piece
There is, however, a third-party plugin for Zotero, the free and open-source reference manager, that offers a far more reliable referencing solution. I therefore thought it might be worth offering a step-by-step guide to incorporating this plugin into your established Markdown workflow.
This tutorial assumes that you’re using, and have already installed, pandoc and its version of Markdown, as advocated in the previous post. It also requires you to use Zotero to handle your bibliography. While other programs, such as EndNote or Reference Manager, may have similar workarounds, I’ve not managed to discover them. In any case, I’d recommend Zotero as the best reference manager for both individual and collaborative writing projects.
Beyond this, however, there are no software prerequisites. One of the particular strengths of Markdown is its flexibility and platform-independence, and the steps below will work using virtually any combination of text editor and word processor.
Using Zotero references in Markdown, step by step
1. If you haven’t already, install Zotero and the plugin for your preferred word processor (currently, Word or LibreOffice are offered).
2. Install the ‘RTF/ODF-Scan for Zotero’ plugin from its GitHub page – this is the plugin that acts as a bridge between your plain text Markdown file and your bibliographic database in Zotero.
3. The plugin adds a new citation style to Zotero, which you will need to set as the default style for exporting citations into other programs. To set this up (on the standalone Zotero client, at least), go to Edit->Preferences. Go to the ‘Export’ tab, and in the dropdown list under ‘Default Output Format’, choose ‘Scannable Cite’.
The ‘Scannable Cite’ format is not a normal, human-readable citation style, such as MHRA or Chicago, but a form of plain text code that looks like this:
|
|
Since this is plain text, it can be inserted into Markdown files, then later read by Zotero and translated into its standard editable citation format in the converted document.
4. Open your text editor, and start some academic writing in Markdown. You are, alas, on your own for this one.
5. When you need to insert a reference into your work, find the source in Zotero, select it, then use Zotero’s ‘Quick Copy’ feature (by default, Ctrl+Shift+C) to copy its ‘Scannable Cite’ code. Using ‘Quick Copy’ (rather than right-clicking and selecting ‘Create bibliography from item’) is the only way this will work.
You can then paste the code into your Markdown file at the point where you want the citation to appear:
in the text, for author-date citation styles:
|
|
in a footnote, for many other citation styles:
|
|
if you are as yet unsure about whether you will be using a footnote or author-date citation style, or would like to keep your options open for other reasons, worry not – you will be able to switch between the two later using the Zotero word processor plugin. For now, choose whichever option you find less intrusive.
6. You can also add various additional pieces of information to the ‘Scannable Cite’ code, if you would like them included in your citation:
7. It is also possible to paste two or more references alongside each other:
|
|
These will be treated as a single citation by Zotero.
8. When your document is finished, convert it to an .odt file using pandoc, as described in the previous guide.
You must use the .odt format for the next few steps of this process to work. Fear not – you can convert the document to .docx or any other format after you’re done.
9. In Zotero, select Tools->RTF Scan. The following dialog box will appear:
Select the ‘ODF (to citations)’ option at the top, then navigate to your saved .odt document and select it as your ‘Input file’. When you select ‘Choose file’ for the ‘Output file’ field, Zotero will automatically suggest a file with the same name as the .odt original, with the suffix ‘(citations)’ – feel free to rename it, and to save it to any location you prefer.
Select ‘Next’, and Zotero will scan your .odt file for any ‘Scannable Cite’ codes, replacing them with entries from your Zotero database.
10. Once Zotero has finished, open up the new .odt file in your word processor of choice. You will see the editable Zotero citations highlighted throughout the document.
Keep Zotero open throughout the following step – the program needs to remain open in order to communicate with the word processor plugin.
11. Go to the options for the Zotero plugin in your word processor, which should look similar to this:
Select ‘Set Document Preferences’, which will bring up a further dialog box:
Choose whichever citation style is appropriate for your work from the list, leaving the other options as they are unless you have good reason to fiddle with them, and select OK. Zotero will then refresh all the citations throughout your document, formatting them in the chosen style.
It is at this point that Zotero will be able to convert your in-text citations to footnotes, or vice-versa, depending on which style you have opted for.
12. At this stage, you’re essentially finished: you should have a document populated with editable citations in your chosen style, which can be refreshed if you change any information in your Zotero database.
If you want or need your finished document in a different format, you can now re-save it using Save As in your word processor. This will, however, also convert your editable citations into normal text, cutting their link to your Zotero database. This should therefore be the last thing you do before printing, submitting, or otherwise washing your hands of the document.
The best of both worlds
Although this method may seem a little convoluted and time-consuming at first, it amounts to little extra effort in practice. The first few steps (1 to 3) need only ever be done once, while the most involved stages (steps 10 to 12) are done only at the end of a piece of work, once the writing itself is complete. You can therefore incorporate them with relative ease into the series of ‘post-production’ tasks that accompany any academic writing work.
For most of the writing process, you need concern yourself only with pasting in and keeping track of the unobtrusive ‘Scannable Cite’ references, without even thinking about the format of these until the very end.
Moreover, this technique brings with it all the advantages of a Markdown workflow:
- a cleaner, stripped-down writing environment;
- fewer distracting formatting options than is the case in a word processor;
- less intrusive formatting and structural code than that used by LaTeX;
- smaller file sizes; and
- freedom to choose the text editor and word processor that best meet your aesthetic, collaborative and compatibility requirements. The only programs this method depends on are Zotero and pandoc, both of which are immensely versatile (and free) tools, and are therefore worth considering in their own right.
Occasional irritants, such as the inability to predict word counts until the references have been converted at the end, are less of a problem than many of the headaches associated with word processing your academic writing.
In short, handling references in this way allows you to combine the slickness of Markdown with the convenience and flexibility of Zotero’s word processor plugins, crafting a superbly efficient and sustainable system – a system that, after two years of continual use, I’m happy to endorse.
For more information on Zotero’s ‘RTF/ODF-Scan’ plugin, see The Zoteroist’s post discussing it. If you’ve given this method a try, or if you use a different method entirely to handle references in Markdown, I’d love to hear about it – feel free to comment!
