-
Notifications
You must be signed in to change notification settings - Fork 5
Initial setup
So, you've got a Markdown document, a Zotero library with papers and books you're referencing, and someone demanding a Micro$oft Word .docx document on their desk by 5pm. Now what?
Well, you've got two options:
- Respond with a passionate, eloquent email espousing the merits of open source software; the lasting value, flexibility, and universality of readable, plain-text formatting; the dedication of the community who made it happen; and the woes of entrusting your data to corporations who rely on walled garden business practices to make money.
- Convert your Markdown document to a Word document with DocDown.
DocDown needs the following things to work:
- Zotero Standalone
- An exported library generated with the Zotero Better BibTeX plugin
Zotero comes bundled with some default variants of the following, but custom versions can optionally be provided:
- A CSL file
- A reference .docx document
And even more optionally:
- Your own locally installed versions of Pandoc and Pandoc-citeproc, although DocDown comes bundled with binaries of both so you'll only need them if you have a specific use case in mind.
Follow this guide to get your system configured.
- Install Zotero standalone for your computer (not just the browser plugin). Use it to store papers and other media you're planning to reference.
- Install Zotero Better BibTeX, a plugin for Zotero which allows you to pin a unique citation key to every document in your Zotero library, export your Zotero library into a variety of useful formats, and keep those exported databases automatically updated. And those aren't even its only features! ❤️
- Once Better BibTeX is installed, head to the File menu in Zotero and click Export Library. You are about to create an auto-updating list of all the citation keys in your Zotero library! For Format, select 'BetterBibTeX JSON'. Don't tick any of the other boxes apart from 'Keep updated'. Select where to save this file - I keep mine in my Dropbox.
- Now go to Edit > Preferences > Better BibTeX. Go to the Automatic Export tab. You should see your newly exported library. I changed the Automatic export option here to On change, which means it'll update my library as soon as I change or add anything to Zotero, but you can keep yours however you want. Another useful setting you may want to look at here is Citation keys > Citation key format, which controls how your keys look (I use '[auth:lower][year]', which results in, for example, 'bong2013' to refer to Bong Joon-ho's 2013 film Snowpiercer).
Better BibTeX comes with a powerful feature called cite-as-you-type, which pops up a quick-search bar to allow you to find a document in your Zotero library and add the citekey straight to your text editor of choice. There are a variety of cite-as-you-type implementations; I detail a setup on macOS using a tool called zotpick-applescript in this blog post, steps 6-9. For other implementations, including for Linux, which I now use, check this page in the Better BibTeX documentation.
CSL (Citation Style Language) files contain rules to convert raw bibliographical data into formatted references for every citation style guide under the sun. DocDown comes with a couple of inbuilt common ones, but you can also head to the CSL repository and download your favourite arcane style. Download this file and save it somewhere sensible.
As with CSL files, DocDown comes with a couple of inbuilt straightforward reference .docx styles, which control how the Word document output looks. You can also create your own: check out the guide in the Pandoc manual (search for 'reference docx').
If you need your own binaries of Pandoc and Pandoc-citeproc, you can install them for most operating systems: follow the Pandoc installation guide. DocDown will use its own bundled ones by default.
Now your system is ready for DocDown to do its magic. See the Installation instructions for details.