How I Generate my CV from BibTeX and Markdown

Recently, Nate Matias mentioned looking to automate the creation of his CV, which I already do. Since he asked, I figured I’d pull together a simple guide for how I manage this, and go from there.

Why Do This?

Before jumping into how, I thought it maybe made sense to talk about why. For me, it’s about reduction of effort. My website already has a Publications Page, and at one point I was hosting my blog on my own and had aspirations to cite papers within blog posts too. So I spent the time to figure out how to hook BibTeX into the static-site generator (Pelican) I use to build the rest of my website, so that I’m able to put BibTeX entries in one .bib file, and then reference the citation key as needed elsewhere on my website.

TL;DR: The General Process, and Reference Files

Here I’ll just provide the steps I use to do this. Links here are to the various specific files/etc. that you could use as templates to replicate my setup. I provide more details below. 1. Use Pelican as a static-site generator 2. Use Pandoc as the markdown-to-HTML renderer (via the pandoc-reader plugin), and to read my BibTeX file with my various papers and publications 3. Write my CV in markdown, which gets generated to HTML (with specific CSS), and ‘printed’ (using WeasyPrint hooked into Pelican like this) to take that and make a PDF.

How did I make this happen

There are a number of steps and hacky configurations I’m using to currently do this, but I’m gonna try to enumerate it here.

Pelican

I use Pelican as my static-site generator. I’m not sure it’s the best tool, but it’s the one I have right now. Partially this is because Pelican supports a number of plugins that I use for this purpose.

pandoc-reader

Pelican has a concept of ‘readers’, which is what it uses to translate between the input format (markdown in my case), and the output format (often HTML, but can be others, I believe). I’m using the pandoc-reader plugin, which passes the input markdown to the pandoc tool.

In order to ensur that pandoc behaves the way that I want, I pass a number of arguments to the tool. These arguments would normally just be command-line flags, but Pelican will pass them using the following code in my pelicanconf.py file:

PANDOC_ARGS = [
  '--csl=/path/to/acm-sigchi-proceedings.csl',
  '--bibliography=/path/to/publications.bib'
]

PANDOC_EXTENSIONS = [
  '+mmd_link_attributes',
  '+definition_lists',
  '+smart',
  '+citations'
]

In essence, the above arguments are telling pandoc which csl file to use in formatting a citation, and where to find the .bib file I use. Further, I use a number of extension flags for pandoc (which are often available by default when you install pandoc). I use a slightly modified csl file, to generate the full citation. The salient part for this purpose is +citations, which enables the pandoc citations extension. Because of my modified CSL file, I think this breaks the inline citation functionality, and I should fix that at some point. However, when I refer to the BibTeX key in my markdown (e.g. @TOCHI_SharingEconomy), it will expand to the full citation, like so (though this is block-quoted for emphasis):

Jacob Thebault-Spieker, Loren Terveen, and Brent Hecht 2017. Toward a Geographic Understanding of the Sharing Economy: Systemic Biases in Uberx and Taskrabbit. ACM Trans. Comput.-Hum. Interact. 24, 3: 21:1–21:40. https://doi.org/10.1145/3058499

Generating a PDF CV

The functionality that pandoc-reader provides enables my Publications page as well as my HTML CV, both of which have very similar input markdown, but get rendered differently. For my HTML CV, I use this CSS, for the HTML that gets rendered from markdown like this (current as of 07/09/2020).

The next step, then is to transition my HTML CV page to a PDF. For this, I use a modified version of the Pelican PDF generator. Generators in Pelican are similar to readers, and can generate different outputs. For now, I’m going to zip up my version of this and share it here, but eventually I need to get this on github. Basically, I’ve set up WeasyPrint to generate a PDF version of my CV from my HTML CV.