The Markdown Resume

Maintaining a resume is one of those annoying tasks that always takes up much more time than it should. Compounding this is the fact that resumes are regularly requested in different formats: raw text, pdf, Microsoft Word, etc. In addition, it might be desirable to have a HTML version online somewhere for added visibility. How then to manage this complexity? No one wants to manually update four versions of their resume, and the pdf conversion tools included with word processors leave much to be desired.

Christophe-Marie Duquesne has a great blog post in which he shows that using the document translation tool pandoc, you can maintain your resume in markdown format and convert to other formats such as html and Word at will.

This is convenient because:

• It means there is only one file you need to update to make any changes.
• Markdown is designed to be human-readable, so if you need a raw text version of your resume, no transformation is needed.
• Markdown has syntax for section headers, lists, tables and more, so you can add as much structure as you want to your resume.
• Being a format designed (partly) for human consumption and creation, it is also an appropriate format to keep in version control.

This is what a simple resume in markdown format looks like:

However, in the above approach the generation of a pdf version (arguably the most important) is problematic. The suggestion is to use the wkhtmltopdf tool, which takes the pandoc-generated HTML and uses the webkit browser engine to generate a pdf. While this will preserve the look and feel of the resume, the pdf output is suboptimal, as webkit is not a typesetting engine. Most importantly, it does not handle page breaks well -- in some cases even putting a page break right across a line of text.

On the other hand, TeX-based typesetting systems are designed for this task. Moreover, pandoc supports two types of TeX output: LaTeX and ConTeXt. I chose the latter since it seemed interesting, is more focused on page layout, and is not specifically geared towards scientific documents. Through trial and error, I was able to create a style.tex which comes close to emulating Christophe-Marie's style.css, resulting in a nicely typeset pdf resume which looks quite similar to the HTML:

HTML version of the resume:

PDF version of the resume:

The repository is here (pull requests welcome!), and it includes a Makefile, so the instructions to make your own resume are:

git clone https://github.com/mszep/pandoc_resume
cd pandoc_resume
vim resume.md   #insert your own resume info
make

You will need both pandoc and ConTeXt installed on your system, which on Debian and derivatives can be achieved with

sudo apt-get install pandoc context