A New Way In Writing Documents With Markdown and Pandoc

Before the holidays started, I had to write a report for class on a programming project I had been working on for nearly a month. I was unsure how I should write this report. Should I use Latex, markdown, or Microsoft Word? Considering this report wasn’t going to be published in some scientific journal, and I don’t know Latex, it was decided that the overhead of the learning and initializing Latex wasn’t worth the effort. Besides, did I mention that I had three days to write this twelve-page report? I didn’t want to mess with anything related to formatting. I only wanted to focus on the content. With those goals, I decided on writing everything in Markdown. With nothing but a black background with white letters on my computer, I quickly progressed.

There was a problem. The simplicity of markdown is also its downfall. I believe my professor would have frowned on me printing off pages of markdown and turning those in (then again, as a computer scientist, he may have appreciated it). Then I discovered pandoc, which is a universal document converter and one of the supported conversions is from markdown to a word document. The thought was that once I had content all written in markdown I would run pandoc, convert it into a word document, and then do a tiny bit of styling off the default. This command was all I needed to know:

#!/bin/bash
# Create a word document from markdown documents
pandoc -f markdown -t docx -o feature-documents.docx \
    s1-description-document.md \
    m4-description-document.md

The added bonus here was that I could have multiple markdown documents spread across the project and then pandoc would concatenate them together into a single word document.

I plan to use this technique in the future. Markdown can be edited on any system, so I had no problem editing it on a Linux machine that housed the project, as well as on Windows. It is in my opinion that no other format or application can beat the simplicity of markdown and the expressibility of Word. OpenOffice or LibreOffice are an option for cross platform, but I believe that Word creates the nicest looking documents with minimal effort. The biggest downfall with word format (.docx) is that it is not source control friendly (just try to open a word document in notepad and you’ll see a lot of non-text). Since I’m moving everything that I do into source control, I’ll keep the content in markdown, and use pandoc to translate it into a word document to get something stylish.

It should be noted that I am not creating everything new in markdown. When I have an English paper that is self-contained (i.e., not part of a larger project) it is much simpler to just write it in Word, and have Word keep track of citations, pages, and table of contents.