-
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 has two operation modes:
-
Plain text mode exports your Markdown document into a Word document with citation keys (which look like
[@author2023]) converted into plain-text citations, according to a specified citation style and using an exported Zotero bibliography. Plain text mode was the only mode prior to version 0.6. - Live citations mode harnesses the amazing live citations functionality of BetterBibTeX. It exports your Markdown document into a Word document with citation keys converted into Word-compatible live citations which are linked to your Zotero library. These can then be managed and synced through the Zotero plugin for Word.
DocDown needs the following things to work:
- Zotero Standalone, with the Better BibTeX plugin installed
- For plain text mode only, an exported library generated with the Zotero Better BibTeX plugin
DocDown comes bundled with some default variants of the following, but custom versions can optionally be provided:
- For plain text mode only, a CSL file
- A reference .docx document, for customizing the styles of the output Word document
And even more optionally:
- Your own locally installed version of Pandoc (at least version 2.18), although DocDown comes bundled with a Pandoc binary so you'll only need this 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! ❤️
If you are planning to use plain text mode, you need to also do the following:
- 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 'Better CSL JSON'. Don't tick any of the other boxes apart from 'Keep updated'. Select where to save this file - I keep mine in my Nextcloud.
- 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).
For further setup and usage information on live citations mode, see the dedicated page.
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 binary of Pandoc, you can install it for most operating systems: follow the Pandoc installation guide. DocDown will use its own bundled one by default.
Now your system is ready for DocDown to do its magic. See the Installation instructions for details.