---
Title: Academic Markdown and Citations
Subtitle: A workflow with Pandoc, BibTEX, and the editor of your choice.
Date: 2015-07-26 13:50
Tags: [workflow, writing]
Summary: >
Managing citations is painful—especially in plain text. But with a little
setup, Pandoc and BibTEX can take a lot of the pain out of it, whether for
Word documents or a static site generator.
Modified: 2015-07-26 20:07
...
Much of my past few weeks were taken up with study for and writing and editing
[a paper] for one of my classes at Southeastern. I've been writing all of my
papers in Markdown ever since I got here, and haven't regretted any part of
that... except that managing references and footnotes has been painful at times.
[a paper]: http://v4.chriskrycho.com/2015/not-exactly-a-millennium.html
Footnotes in Markdown look like this:
```markdown
Here is some text.[^fn]
[^fn]: And the footnote!
```
This poses no problems at all for normal footnotes. Academic writing introduces
a few wrinkles, though, which means that this has always been the main pain
point of my use of Markdown for writing papers.
Many academic citation styles (including the Chicago Manual of Style, on which
our seminary's [style guide] is based) tend to have a long version of the
footnote appear first, followed by short versions later. Nearly _all_ academic
citations styles make free use of the ["ibid."] abbreviation for repeated
references to save space, time, and energy. Here is how that might look in
manually-written footnotes, citing the very paper in which I sorted this all
out:
```markdown
Some text in which I cite an author.[^fn1]
More text. Another citation.[^fn2]
What is this? Yet _another_ citation?[^fn3]
[^fn1]: So Chris Krycho, "Not Exactly a Millennium," chriskrycho.com, July 22,
2015, http://v4.chriskrycho.com/2015/not-exactly-a-millennium.html
(accessed July 25, 2015), ¶6.
[^fn2]: Contra Krycho, ¶15, who has everything _quite_ wrong.
[^fn3]: ibid.
```
[style guide]: http://www.press.uchicago.edu/books/turabian/turabian_citationguide.html
["ibid."]: https://en.wikipedia.org/wiki/Ibid.
This seems straightforward enough, though it is a bit of work to get the format
right for each different kind of citation (articles, books, ebooks, electronic
references to articles...). Things _really_ get complicated in the editing
process, though. For example, what if I needed to flip the order of some of
these notes because it became clear that the paragraphs needed to move around?
This happens _frequently_ during the editorial process. It becomes particularly
painful when dealing with the "ibid."-type references, because if I insert a new
reference between two existing references, I have to go back in and manually add
all that the reference content again myself.[^footnotes]
Enter Pandoc and BibTEX.
## Managing Citations
The idea of plain-text solutions to academic writing is not especially new; only
the application of Markdown to it is---and that, only relatively. People have
been doing this, and [documenting their approaches][healy], for quite a while.
Moreover, tools for managing references and citations have existed for quite
some time as well; the entire [LATEX][latex] toolchain is largely driven by the concerns of
academic publishing, and as such there are tools in the LATEX ecosystem which
address many of these problems.[^latex]
[healy]: http://kieranhealy.org/blog/archives/2014/01/23/plain-text/
[latex]: http://www.latex-project.org
One such is BibTEX, and the
later (more capable) BibLATEX: tools for managing bibliographies in LATEX
documents. The BibTEX/BibLATEX
approach to managing citations in a document is the use of the `\cite` command,
with the use of "keys" which map to specific documents: `\cite{krycho:2015aa}`,
for example.
This is not Markdown, of course. But other folks who have an interest in
Markdown and academic writing have put their minds to the problem already. Folks
such as Jon MacFarlane, the originator and lead developer of [Pandoc], perhaps
the single most capable text-conversion tool in existence. As it turns out,
Pandoc Markdown supports a [citation extension] to the basic markup. It's just a
variant on the BibTEX
citation style that feels more at home in Markdown: a pair of braces and an `@`,
plus the citation key, like `[@krycho]`. Moreover, Pandoc knows how to use BibTEX libraries, as well as many
others, and [Citation Style Languages][csls] (CSLs) to generate
markup in _exactly_ the format needed for any given citation style.[^citeproc]
[pandoc]: http://pandoc.org
[citation extension]: http://pandoc.org/README.html#citations
[csls]: http://citationstyles.org
Instead of writing out all those citations details by hand, then, I can just
format my footnotes like this (assuming the citekey I had set up for the article
was `krycho:revelation:2015`):
```markdown
Some text in which I cite an author.[^fn1]
More text. Another citation.[^fn2]
What is this? Yet _another_ citation?[^fn3]
[^fn1]: [@krycho:revelation:2015], ¶6.
[^fn2]: Contra [@krycho:revelation:2015], ¶15, who has everything _quite_ wrong.
[^fn3]: [@krycho:revelation:2015].
```
This is much simpler and, importantly, has the exact same form for each
citation. Pandoc will take care of making sure that the first reference is in
the long form, later references are in the short form, and repeated references
are in the "ibid." form as appropriate. It even renders a properly sorted and
structured Works Cited section.[^styleset]
The slightly complex command I used to generate a Word document from a Markdown
file with citations (using my own BibTEX library and the Chicago Manual of Style
CSL) on the command line is:[^template]
```bash
$ pandoc revelation.md --smart --standalone \
--bibliography /Users/chris/Documents/writing/library.bib \
--csl=/Users/chris/Documents/writing/chicago.csl -o revelation.docx
```
To see an extended sample of this kind of usage in practice, take a look at the
[Markdown source] for the paper I wrote last week, using exactly this approach.
Every footnote that references a specific source simply has a cite key of this
variety. The header metadata includes a path to the bibliography file and a
CSL. (These could be configured globally, as well, but I chose to
specify them on a per-file basis so that if I want or need to use _different_
styles or a separate library for another file at a later time, I can do so with
a minimum of fuss. More on this below.)
[markdown source]: http://v4.chriskrycho.com/2015/not-exactly-a-millennium.txt
[Here] is the rendered result. You can see that it automatically generated
everything right down to the "ibid."-style footnotes. I made a few, fairly
minimal tweaks (replacing the search URL with an ATLA
database catalog reference and inserting a section break before the Works Cited
list), and turned the paper in---confident, for the first time since I started
seminary, that all of the references were in the right order and the right
format. With carefully formatted reference documents (with their own style
sets),[^reference] I was able to generate an actually _nice_ [PDF]
version of the paper from another Word document, as well.[^pdf]
[here]: /downloads/revelation.docx
[pdf]: /downloads/revelation-pretty.pdf
And, better yet, you don't even have to put citations in footnotes. As
[\@anjdunning] pointed out in a [tweet] response to the original version of this
post:
[\@anjdunning]: https://twitter.com/anjdunning
[tweet]: https://twitter.com/anjdunning/status/625415216575197184
> [\@chriskrycho] Don't put citekeys in a footnote: write everything as inline
> citations and it will also generate notes when asked by CSL def.
> [∞](https://twitter.com/anjdunning/status/625415216575197184) July 26, 2015 17:19
[\@chriskrycho]: https://www.twitter.com/chriskrycho
In my standard example from above, then, you could simply do this:
```markdown
Some text in which I cite an author.[@krycho:revelation:2015, ¶6]
More text. Another citation.[Contra @krycho:revelation:2015, ¶15, who has
everything *quite* wrong.]
What is this? Yet _another_ citation?[@krycho:revelation:2015]
```
This will generate the same markup for my purposes here; and as [\@anjdunning]
noted, it goes one step further and does what's appropriate for the
CSL. This might be handy if, for example, you wanted to use the
Chicago notes-bibliography style in one format, but switch to a simpler
parenthetical citation style for a different medium---or even if you had a paper
to submit to different journals with different standards. Having the citations
inline thus has many advantages.
Now, there are still times when you might want to split those out into distinct
footnotes, of course. That second one is a good candidate, at least for the way
I tend to structure my plain-text source. I find it useful in the case of
_actual_ footnote content---i.e. text that I'm intentionally leaving aside from
the main text, even with reference to other authors---to split it out from the
main flow of the paragraph, so that someone reading the plain text source gets a
similar effect to someone reading the web or Word or PDF versions,
with the text removed from the flow of thought. In any case, it's quite nice
that Pandoc has the power and flexibility such that you don't _have_ to.
Finally, you don't actually _need_ the brackets around the citekey, depending on
how you're using the reference. If you wanted to cite the relevant author
inline, you can---and it will properly display both the inline name and a
reference (footnote, parenthetical, etc.) in line with the CSL
you've chosen. If I were going to quote myself in a paper, I would do something
like this:
```markdown
As @krycho:revelation:2015 comments:
> This was a hard paper to write.
```
This is _extremely_ powerful, and while I didn't take advantage of it in my
first paper using these tools, you can bet I will be in every future paper I
write.
### All those references
Of course, as is probably apparent, managing a BibTEX library by hand is no joke. Entries tend to look
like this:
```tex
@book{beale:revelation:2015,
Date-Added = {2015-07-20 21:16:02 +0000},
Date-Modified = {2015-07-20 21:21:05 +0000},
Editor = {G. K. Beale and David H. Campbell},
Publisher = {William B. Eerdmans Publishing Company},
Title = {Revelation: A Shorter Commentary},
Year = {2015}}
```
While there is a lot of utility in having that data available in text, on disk,
no one wants to _edit_ that by hand.[^noone] Gladly, editing it by hand is not
necessary. For this project, I used the freely available [BibDesk] tool, which
is a workable (albeit not very pretty and not _very_ capable) manager for BibTEX:
[bibdesk]: http://bibdesk.sourceforge.net
Once I filled in the details for each item and set a citekey for it, I was ready
to go: BibDesk just stores the files in a standard `.bib` file on the disk,
which I specified per the Pandoc command above.
BibDesk gets the job done alright, but only alright. Using a citation and
reference management tool was a big win, though, and I fully intend to use one
for every remaining project while in seminary---and, quite possibly, for other
projects as well. Whether that tool is BibDesk or something else is a different
matter entirely. (More on this below.)
## To the web!
I wanted something more out of this process, if I could get it. One of the
reasons I use plain text as a source is because from it, I can generate Word
documents, PDFs, and _this website_ with equal ease. However,
Python Markdown knows nothing of BibTEX or citekeys, to my knowledge---and since I render
everything for school with Pandoc, I have long wanted to configure [Pelican] to
use Pandoc as its Markdown engine instead of Python Markdown anyway.
[pelican]: http://docs.getpelican.com/en/3.6.0/
As it happens, I actually set this up about a month ago. The process was pretty
simple:[^pelicanconf]
1. I installed the [pandoc-reader] Pelican extension.
2. I set the plugin path in my Pelican configuration file.
3. I specified the arguments to Pelican I wanted to use.
The only additional tweaks necessary to get citation support were calling it
with the `'--filter pandoc-citeproc'` arguments, which lets it process any
bibliography data supplied in the header metadata for the files. Calling Pandoc
with `--bibliography