I’ve written before about both my Pandoc workflow and my use of Texts when producing various documents for work. An excellent recent article by Kieran Healy on his own plain text workflow using Pandoc prompted me to overhaul my own rather complex setup for longer documents. If you’re new to using Pandoc, or if — like me — you had an existing workflow that was in need of a bit of pruning, I highly recommend Kieran’s article. I have now abandoned my rather Byzantine system for building documents of different formats, and use his simple Makefile instead. I keep a copy in my ~/.pandoc directory, and then copy it into the directory of my current writing project for tweaking. I’ve also added a target for .docx export, which is often what I need when collaborating with others. If I am leading the writing, I write in Markdown, convert to PDF or HTML for myself (Kieran’s CSS for Marked is a lovely way to preview your document in real-time as you write), and then export to Word format for my co-authors to comment on. I then incorporate their changes manually back into the Markdown document, and start the process again¹.

His article also made me overhaul my citation system. As he says, the most flexible way to include citations is to use Pandoc’s own in-text citation placeholders, as these will be exported to every relevant format, including HTML and Word. Pandoc requires you to place the references in square brackets, with each reference identifier separated with a semi-colon and preceded by an @ symbol, like so: [@Bloggs2012; @Smith1999]. Previously, when writing documents that needed references, I have tended to either just use BibTeX in-text citations and then export via (Xe)LaTeX, or I have attempted to copy the citation identifier manually from my reference manager, Bookends, and manually create the correct Pandoc citation format in my document.

Now, I know for sure that someone contacted me by email after reading one of my articles on Pandoc or Bookends to ask me how I integrated the two². At the time, I had no good answer, but motivated now by Kieran’s article, I searched again for a solution. Some kind person had asked the question on Bookends’ forum (who knows, it could even be the same person who emailed me³) and got a helpful reply from Jon. For my mystery emailer, and for any other person who might need more detailed guidance, here’s how you do it.

Step 0

You need to export your reference collection into one of the formats supported by Pandoc. In practice, this is likely to be either BibTeX or Endnote XML format, both supported by Bookends’ export command. I find exporting to Endnote quicker, and as I prefer to export my entire reference collection periodically (currently over 2700 references), speed makes a difference. Depending on the way you work, you could create a static group in Bookends for each paper as you write it, and drag in the relevant references. Then you would select all of the references in that group as Hits and export them. Whichever way works best for your workflow, you need to specify the export file you have just created in the --bibliography option in your Makefile and Marked setup, as described by Kieran Healy in his article.

Step 1

The key (pun intended) is that you need to set up Bookends to produce a citation key field (which gets stored in the field User1) when you import references. If you have been using Bookends to generate BibTeX format, you might have set this up already. You need to go to the BibTeX preference pane in Bookends and check the boxes as below. Note: don’t check the “Copy Citation copies Key field box”, because this will override the work we’ll do in a minute. If you don’t have keys in your User1 field already, you’ll need to add them manually before we go further. You can do this by selecting all your references and using the Refs > Generate BibTeX key command.

Step 2

Now we need to set up a new bibliographic format. Go to the menu item Biblio > Formats manager... and you should get a window like the one below. Click the + button at the bottom left of the window to create a new format and call it something meaningful. I’ve used ‘Pandoc Citation’ here. As far as I know, we only need to edit the ‘Bibliography Options’ tab, because we are creating a format just for the temporary citations in your document. For each of the types of reference in the drop-down list at the top, paste the text $@$u1 in the Field Order box, deleting any existing text in that box. If you need to add additional types of reference (like ‘Internet’), do that via the Type dropdown and paste in the same code. This code will insert a literal @ symbol, then the contents of the User1 field, which is where we are keeping our citation identifiers. Once you have finished, close that window.

Step 3

All that is left to do is to tell Bookends that we want to use the bibliography format we’ve just created. Open Preferences and find the Scan & Bib tab. Citation delimiters needs to be set to square brackets, and multiple citations separated by semi-colons. Then in the Copy Citation group, you find the bibliography format you have just created in the Use: dropdown and select that.

Citing references

Now we can use our new system. In your Markdown document, leave the insertion point where you want to insert your citation and switch to Bookends. Find and select the references you want to cite, then choose Edit > Copy Citation (or Cmd+Y on a Mac). Switch back to your text editor, and paste. You should find the citation identifiers inserted in the correct Pandoc format. If you have set up your Makefile (and/or Marked) correctly with a reference to your Bibliography file (see Step 0) and appropriate CSL style (if you don’t want the default Chicago reference style), your references should be beautifully rendered in your output document or Marked window.

One final thing that took me a little time to discover. If you’re like me and use the handy Edit > Copy Formatted (or Cmd+K) command to copy a formatted version of a bunch of references for pasting into an email or other quick document, you need to set Biblio > Default Format to a more conventional bibliography format like Harvard, or whatever you prefer. Copying citations will still use your Pandoc format because of the setting in the Scan & Bib tab of Preferences. That way you get the best of both worlds.

Update 2014-02-08: It was Tamás Nagy (@tlngy on Twitter) who contacted me — on Twitter, not email — which explains why I couldn’t find the email! He was also the person who asked the question on the Bookends forum, for which I’m very grateful. Thanks Tamás!