Use Jekyll for Your Academic Site

February 21, 2014

If you’re a grad student and building your personal academic Web site, you have many choices for tools. I think you should use Jekyll.

You should make a personal site

In case you’re not convinced yet, you (a grad student) should definitely have a Web site—and you should have a blog. There are so many reasons:

Use a static site generator

The world is overflowing with CMSes and they are almost all crap. WordPress might suck the least and even it is unconscionable. Because you’re a nerd, what you want is a static site generator, which is a simple tool that takes a few text files and compiles them into a Web site. You can check your content and design into a VCS, share your source on GitHub, and use scp to deploy output to your department’s servers with zero setup on the host. Traditional CMSes can’t do any of this.

To be clear, you do not want to code the entire site entirely by hand. SSGs take the tedium out of making multiple pages look consistent, generating RSS feeds, and the like.

The best static site generator is Jekyll

I’ve tried out a great many static site generators—Hyde, Pelican, Nanoc, and Middleman, to name a few—and Jekyll is the best. There’s almost nothing to an SSG, which is why so many people are tempted to write them (I have been). Jekyll is not better than the rest for any fundamental design reason; it’s better because it’s enormously popular and therefore excels in the long tail of details. It has great documentation, a thriving plugin and tool ecosystem, and frequent bug fixes. In my experience, it has much fewer frustrating corner cases compared to Nanoc and Pelican.

Jekyll isn’t perfect, but it’s as close as these things get.

If, like me, you secretly believe that everything is better if it’s written in Python, I still suggest you start with Jekyll (which is done in Ruby). In my experience, using Jekyll does not require writing or reading a single line of Ruby.

I’m in the middle of moving my site from Nanoc to Jekyll. In case you need it, here’s a tiny Python script for translating Nanoc post files into Jekyll files.

But Liquid templates are awful

One drawback to Jekyll currently is its template language, Liquid. Whereas Jekyll excels in the details, Liquid dies by them. (Fortunately, the developers seem to be planning to add alternative template languages in a future release.)

Here are some terrible things about Liquid that you should watch out for if you use Jekyll:

Liquid is awful, but Jekyll itself is so not-awful that it justifies putting up with Liquid’s quirks.