Markdown and Academic Writing

Markdown took over my writing life this semester, as I’ve mentioned. I took nearly all my class notes in Markdown (after a brief interval of using Evernote and an even briefer pass with Microsoft Word—neither of them quite worked for me, especially as my addiction grew). The only hiccup with my growing delight in the combination of Markdown and Byword was the challenge of writing papers in them. There was little question for me that it was worth the few additional wrinkles it entailed, however: a nice clean writing environment and the obviousness of Markdown (not to mention the revision-history– and version-control–friendly nature of plain text) inclined me strongly toward using it.

For main paper content—all those lovely paragraphs I hammered out—Markdown was sublime. The trick for my papers this semester, though, was something core to any academic writing: footnotes. The problem isn’t Markdown; just about every version out there (except the original) has support for a simple footnote syntax:

Writing along and now we need a footnote.[^1] Then we go merrily along on our way again.

[^1]: Here's the content for that footnote. Simple enough---obvious, even.

No, the real problem is keeping track of those footnotes. My habit for blog posts and even class notes was to simply put the footnotes at the bottom of the piece. That makes sense for those kinds of content: it’s easy to keep track of the order of the notes, as one generally isn’t massively rearranging blog posts, much less class notes. So I’d simply go in order: [^1], [^2], and so on.

Then I wrote my first major academic paper using Markdown and Byword. Wrangling the footnotes was painful, to say the least. In fact, at one point I switched the order of some of the pieces of the text, and would have had footnotes out of order if, thankfully, the two involved hadn’t been referencing the same author on the same page. In any case, I knew I had to come up with a better system when tackling my second major paper, which promised to entail a much higher number of footnotes, given the greater complexity of the content.

The system I devised worked spectacularly well, so I thought I’d share it in case anyone else is interested in using Markdown for academic writing.

Since footnotes are essentially just another type of link, the text in them can be arbitrary. The text is simply replaced by a numeral—footnotes are always numbers or symbols, and in academic writing, they’re nearly always numbers because one quickly runs out of symbols. So Markdown handles this sensibly. Also, the order of the footnotes simply matches the order they appear in the text (even if you have them out of order where you define the footnote content). Thus:1

In which I make a fool of myself.[^hippies] It's not exactly like that's *hard*.[^frogs]

[^frogs]: Because, you see, I have a lot of practice.

[^hippies]: Why in the *world* would anyone ever put their footnotes out of order? Well, one wouldn't---at least, not on purpose.

The resulting output will look like this:

In which I make a fool of myself.1 It’s not exactly like that’s hard.2


1Why in the world would anyone ever put their footnotes out of order? Well, one wouldn’t—at least, not on purpose.

2Because, you see, I have a lot of practice.

The order has flipped, and the letters have been replaced by numerals, just as one would hope. I put this to good use when working on my paper. As with any well-constructed academic paper, I formulated my argument and made a detailed outline up front. Although the structure of the paper flexed and changed a bit as I went along, this gave me the basic parameters within which I was working at all times. At any given point, I was working in a distinction marked off by at least one top-level (Introduction or Analysis or Conclusion) and often by a subhead. Furthermore, I was always in a paragraph. I simply combined these elements to make up the marker for any given footnote.

My footnote text formula was simple: I put together the first letter of each section followed by the paragraph number (each separated by dashes), followed by the footnote number (actually a letter) for that paragraph. Thus, if I was writing the third paragraph of Section II of the Analysis part, the first footnote would have been “numbered” [^A-II-3a].2 The dashes are useful because they made it clear that I was working on Section 2, Paragraph 3, not Analysis, Paragraph 23. Further, I kept the footnotes immediately next to the paragraph with which they belonged, making it easy to find them and move them as well. Thus, if and when I moved pieces around, I usually only had to change a few numbers related to that footnote—most frequently, just switching the paragraph numbers.

While this was certainly a bit more work than the automatic footnote generation one gets with Microsoft Word, it quickly became a smooth process. Sensible use of find and replace operations made the switches easy enough, and if it took me a few extra minutes to do those elements than it would have in Word, it took me a great deal less time in general because I work so much more quickly in Byword with Markdown than I do in Word.

I hope some people will find the approach I developed useful for their own writing!


Addendum: Extended Example

I thought it might be useful to provide a slightly longer example to demonstrate what the foonoting looked like in practice. As a point of amusement (as well as illustrating one of the rather intriguing behaviors I laid out earlier), note that footnote A-III-5a comes after A-III-5b in the text; I switched the sentence order at some point during the editing, but never bothered changing the footnote order because I knew Markdown would generate the output correctly.

As if anticipating the ways this passage would be abused, Paul quickly moves to restrict its interpretation in the second sub-chiasm (verses 11--12): neither are women independent of men, nor men of women. Just as woman was originally formed from man, now all men are born of women. Thus, although woman was created from and for man, he cannot claim any superiority on that basis: she has become his source just as he was hers. Even more importantly, men and women are mutually dependent "in the Lord"---language that is common throughout Paul's epistles whenever he is calling believers to unity (cf. Ephesians 2:13--21, Philippians 2:1--2, Galatians 3:28). The ontological relationship between the sexes that God established in creation is to be preserved, but characterized by mutual dependence and unity in Christ---not by domineering or abuse.[^A-III-4a]

[^A-III-4a]: Egalitarian and complementarian commentators are united on this point: see e.g. Belleville, 231; Fee, 522--524; Robertson and Plummer, 234; Lockwood, 375--376.

Each sub-chiasm is relatively clear on its own, but the relationships between the sub-chiasms, and between each of them and the turn in verse 10, are less immediately obvious. Indeed, the primary challenge in interpreting this section---and, arguably, of interpreting the entire passage---is understanding verse 10. Translated somewhat woodenly, the sentence reads, "For this reason, a woman ought to have authority on/over her head, because of the angels" (author's translation). The language of the first sub-chasm suggests that Paul might mean be using "authority" (ἐξουσία) metonymously, despite the linguistic oddity of this move.[^A-III-5b]. If so, the passage reads, "a woman ought to have a symbol of authority on her head."[^A-III-5a] On the other hand, Paul's language in the following sentence ("Nevertheless, in the Lord woman is not independent of man") doubly suggests that he means what the text more naturally says: "a woman ought to have authority over her [own] head."[^A-III-5c] First, the use of "nevertheless" sets the second sub-chiasm in contrast to the turn. Second, the fact that Paul begins by emphasizing that woman is not independent of man (rather than vice versa) suggests that it is her authority, not the man's, that is in view.[^A-III-5d]

[^A-III-5a]: So the ASV, ESV, HCSB, NET, NIV 1984, NASB, NKJV, NRSV. Others go even further: NLT, for example, has "a woman should wear a covering on her head to show she is under authority."

[^A-III-5b]: Fee takes the unique nature of this would-be construction, unparalleled in any other Greek usage, as the basis for dismissing it out of hand (519 n. 23)---apparently ignoring his own suggestion, mere pages later, that "*exousia* was one of the Corinthians' own words.... Very likely that is the reason for this choice of words, which otherwise appears to be so unusual" (521), which satisfactorily explains Paul's otherwise odd linguistic choice.

[^A-III-5c]: Fee, 520.

[^A-III-5d]: Fee, 522--523.

The resulting output:

As if anticipating the ways this passage would be abused, Paul quickly moves to restrict its interpretation in the second sub-chiasm (verses 11–12): neither are women independent of men, nor men of women. Just as woman was originally formed from man, now all men are born of women. Thus, although woman was created from and for man, he cannot claim any superiority on that basis: she has become his source just as he was hers. Even more importantly, men and women are mutually dependent “in the Lord”—language that is common throughout Paul’s epistles whenever he is calling believers to unity (cf. Ephesians 2:13–21, Philippians 2:1–2, Galatians 3:28). The ontological relationship between the sexes that God established in creation is to be preserved, but characterized by mutual dependence and unity in Christ—not by domineering or abuse.1

Each sub-chiasm is relatively clear on its own, but the relationships between the sub-chiasms, and between each of them and the turn in verse 10, are less immediately obvious. Indeed, the primary challenge in interpreting this section—and, arguably, of interpreting the entire passage—is understanding verse 10. Translated somewhat woodenly, the sentence reads, “For this reason, a woman ought to have authority on/over her head, because of the angels” (author’s translation). The language of the first sub-chasm suggests that Paul might mean be using “authority” (ἐξουσία) metonymously, despite the linguistic oddity of this move.2. If so, the passage reads, “a woman ought to have a symbol of authority on her head.”3 On the other hand, Paul’s language in the following sentence (“Nevertheless, in the Lord woman is not independent of man”) doubly suggests that he means what the text more naturally says: “a woman ought to have authority over her [own] head.”4 First, the use of “nevertheless” sets the second sub-chiasm in contrast to the turn. Second, the fact that Paul begins by emphasizing that woman is not independent of man (rather than vice versa) suggests that it is her authority, not the man’s, that is in view.5


  1. Egalitarian and complementarian commentators are united on this point: see e.g. Belleville, 231; Fee, 522–524; Robertson and Plummer, 234; Lockwood, 375–376.

  2. Fee takes the unique nature of this would-be construction, unparalleled in any other Greek usage, as the basis for dismissing it out of hand (519 n. 23)—apparently ignoring his own suggestion, mere pages later, that “exousia was one of the Corinthians’ own words…. Very likely that is the reason for this choice of words, which otherwise appears to be so unusual” (521), which satisfactorily explains Paul’s otherwise odd linguistic choice.

  3. So the ASV, ESV, HCSB, NET, NIV 1984, NASB, NKJV, NRSV. Others go even further: NLT, for example, has “a woman should wear a covering on her head to show she is under authority.”

  4. Fee, 520.

  5. Fee, 522–523.


  1. Note the extra spacing between the footnotes. I’m not sure why, but footnotes behave differently than regular links, which can be stacked one after another. Footnotes have to be separated as separate paragraphs—probably because they are paragraph-like entities. Someday I’ll look it up in the implementation to see why. But not today. 
  2. Because of the relatively simple structure of my paper, I actually simplified this, dropping the top-level header and making a few other adjustments. But this is the gist of my approach, and it’s the framework in which I intend to work going forward.

    If you’re curious, I made this footnote with a simple [^2]. Boring

Discussion

  • Filip Witek thought to say:

    Since I also tried writing my academic papers in Markdown, I’m very curious about how you managed to export your second major paper to PDF while perserving pagination-based attributes, such as footnotes printed at the end of each page. I have to submit my papers in PDF and so far, all I could do with Markdown documents was to simply export them to Rich Text Format and take care of the layout in Pages or Microsoft Word. Have you found a way to export Markdown documents to PDF while perserving the required aspects of layout of your academic papers?

    • I cheated: I went via MS Word. I took the document I exported to Word and tweaked the styles a bit. The native PDF export functionality in OS X did the trick nicely for me, though I think I may have used the Adobe PDF conversion instead to reduce the file size with the embedded font file.

      That said, I think the LaTeX tools in Pandoc would probably do it as well; I haven’t tried yet.

    • Oh, and I should note that using Pandoc, you can export directly to Word and even use another document as a template so you can have the desired formatting from the get-go. Likewise with LaTeX/PDF, though I’ve yet to get that set up. I highly recommend Pandoc if you’re going to be doing a lot of Markdown stuff.

  • Dawood thought to say:

    That was an amazing post, and gives me hope that I could actually write my dissertation using Markdown! I currently do something similar to you for footnotes (although put them immediately after I’ve finished the paragraph they are found in so I don’t forget!), and even use the Dropbox text editor to type on my phone whilst on the train to and from school. It’s incredibly useful!

    My problem, however, is how to transform the Markdown footnotes into proper Word footnotes. How did you manage to overcome this issue? I am using Windows (unfortunately it’s what my school uses), and my supervisors etc. are stuck using Word and Office for their writing, so sending them things in pure Markdown will be unsuitable.

    • Excellent—glad to have been of some assistance!

      Your best bet for converting to Word is using pandoc, which lets you export to .docx among a variety of other formats. (Since you’re using it for academia, you may also be interested in looking at how it exports to LaTeX—very handy.) It’s a command line tool, but even if you’re not super comfortable there, it’s pretty easy to use.

      To use pandoc to generate a Word document (with nicely formatted footnotes, smart typography like curly quotes, em- and en-dashes, and so on), you can just run the command pandoc <input document(s)> -S -o my_word_doc.docx at the command line. As documented here, pandoc works on all major platforms, and the documentation is excellent and very thorough.

      A couple notes that you may find helpful:

      • Make sure you add a couple blank lines at the bottom of each file if you combine multiple files; pandoc just combines them all before running its conversion, so without that white space the last line in one file with run right into the first line in the next file. This can cause all sorts of trouble!
        For the same reason, if you do use separate documents (say, for chapters), you will need to make a top-level distinction in footnotes, similar to how I did in this post, for pandoc to distinguish between them successfully. If you have [^A-1] in two documents, it will grab the footnote text from the first one and use that for both pieces. Obviously not what you want.
      • I created a Quick Style set in Word so that I can generate a document and have it styled the way I want pretty much immediately. There is also an option with pandoc to supply a reference document, the styles of which will be applied to the document in question, --reference-docx=<path to reference doc>. There’s a bug with that on Mac, but I believe it works correctly on Windows from what the pandoc developer told me.
      • You can also customize the templates for other kinds of output (like LaTeX templates, which is what I’ve used to generate PDFs like the one on this page). That probably won’t matter to you much at this stage, but it’s nice to know.

      Let me know if there’s any other questions I can answer, and Godspeed on your dissertation!

      • Dawood thought to say:

        Thanks for your quick response!

        I’ve been playing around with Pandoc and MultiMarkdown for a little while now, and think it might actually be more useful for long documents to use the inline footnote function (although that does, of course, mess with word count targets and the like, which would need to be adjusted). If you’ve not come across it, you can just use ^[Inline footnote text here.] directly where you want to enter the footnote in the body text, without anything else required.

        I’ve tried this with some longish documents (conference papers), and it seems to work perfectly, although I haven’t as yet tried linking multiple documents together in Pandoc.

        • Ah, I had not noted that Pandoc supported that. Very handy, and yes, I think that especially for long documents that should be extremely helpful—not least because then you don’t have to worry about managing the numbers yourself. I expect I may take advantage of that myself next time I’m writing a paper like this, so thanks for passing it along.

          Now, if I can just get the folks at Byword to add support for it in their document previews, I’ll be set.

  • Charles Bucher thought to say:

    Great tips! I just discovered the joys of Markdown a few months ago, and over my winter break I discovered the even greater joys of markdown in Drafts and Editorial for URL actions and Workflows. Byword looks gorgeous by the way. I have more than enough apps of this variety, but I’ve been considering it regardless.

    Anyway, my school resumed this past week and I had decided I’d do my homework,messages, and papers in markdown, since I always take notes on my ipad anyway (usually handwritten inNotability).

    What do you do about final formatting, coming from markdown? I’d been using Pandoc on my laptop for a few days, then I discovered somebody’s pythonista script for using Pandoc online and converting to pdf, and modified it to convert to docx, since my professors usually prefer that, and managed to get a workflow running it in Editorial. I feel like there has to be some better ways to deal with submitting, without having to leave the device it’s composed on. Well, sorry for the over-long message. I don’t know if you have more posts or tips about markdown in academic writing, but I’ll be sure to have a look around.

    Charles Bucher

  • Charles Bucher thought to say:

    Just noticed all the comments about Pandoc. Should have looked at those before. Pandoc is wonderful so far, and Docverter is the service that the Pythonista script and workflows use to convert via Pandoc. Thought I’d throw that in. It works pretty decent so far.

    • Definitely. I did two things to automate my workflow with Pandoc:

      1. I set up a theme in Word with the formatting I needed for all my documents (Turabian, ugh) set in the Quick Styles. That way, once I have a Word document, I can just apply that and it’s basically done.

      2. I created an alias on the command line to make it easy and not have to remember everything every time: `pandoc -t docx -f markdown+mmd_title_block -S $*`. That generates .docx files from Markdown with MultiMarkdown title blocks and smartens the quotes, etc.

      You may find [this](https://github.com/dsanson/Pandoc-Droplets-and-Services) set of tools for OS X useful; it provides wrappers around a lot of the conversions.

Discussion is closed at this time.