mathematism

Dec 22

Static Site Generators

A practical comparison and thoughts on 10 tools.

I’ve been thinking quite a bit about how to simplify the technology behind this site in a way that would allow me to focus on writing. django-mingus served me pretty well over the last year and a half, but I wanted to get away from managing a Django app, a database and other requirements related to running a dynamic applicaiton. I decided pretty early on that I wanted to move to a static site generator (SSG). What follows is an account of some research I did and ultimately the tool I landed on.

Criteria

Before I set out to research I created some personal criteria that would help me decide on the right SSG for me:

  • Easy to test drive (like < 5 minutes)
  • Good command line interface (CLI)
  • Active development
  • Active and responsive community
  • Ability to easily deploy changes
  • Extensibility
  • Good documentation
  • Support for markdown (for easy conversion from django-mingus)
  • Support for various markup formats
  • Blog-aware

Contenders

Through some googling and responses to my tweet I was able to generate a decent list of SSGs for comparison:

The above list consists of nine Python-based tools and two Ruby-based tools. It is by no means exhaustive. There are tools out there in many languages. I just chose to focus on Python and Ruby.

Basic comparison

Before I could evaluate the SSGs based on my personal criteria I needed to compare core features. I created a Google spreadsheet to compare features including templating system, syntax highlighting and configuration file type. This allowed me to trim the list before digging into the final contenders more thoroughly.

It’s kind of hard to digest the spreadsheet in that small space. You can also view it as a full page

Based on the core feature comparisons I was able to easily eliminate Blatter, Chisel, Markdoc, Pelican, Pilcrow and Tahchee.

Further examination

To me, this is where things got fun. Looking at my personal criteria I could dig into the tools and further trim the list. I attempted a basic install and setup of each of the following and provide pros and cons for each based on that experience.

Blogofile

Blogofile has quite a few things going for it, aside from the love I’ve been seeing it get on Twitter recently. It has a dead-simple install, extensibility through controllers and filters, good docs and a good CLI. On the down side for me it’s not as active as I’d like and uses Mako templates.

Hyde

Hyde is a port of Jekyll to Python. It has decent docs, is Django-based, has an active commit log and good markup support. The CLI left something to be desired and to me felt like it included too much. Honestly the ramp-up time once I started to dig in exceeded what I was personally willing to invest.

Jekyll

Jekyll is written in Ruby and has spawned a Python port as I mentioned above. I have pretty much the same view of it as Hyde but it has the added advantage of solid docs and a very active community. With the combination of my perceived ramp-up time and actual lack of Ruby skills Jekyll didn’t seem to fit the bill for me.

nanoc

nanoc has thorough docs, a dead-simple install, extensibility through helpers and filters and a superb CLI. In addition it is actively worked on and boasts a discussion group and IRC channel that are responsive. Concerns for me with nanoc were the erb/erubis templates and my lack of Ruby knowledge.

Sphinx

I love ReST and I love Sphinx. I use it all the time for documentation. Sphinx’s docs and community are great. The lack of blog-awareness and the fact that it’s a ReST tool primarily for documentation nixed it for me though.

Showdown

After I got a chance to work with each of the remaining contenders I whittled the list down to Blogofile and nanoc. These two had a good combination of all the features I was looking for in addition to being insanely easy to install and use.

I dug even deeper with both of these tools, converting all of my blog posts to work with each and learning more about their extensibility and deployment features.

In the end I decided to go with nanoc for a few reasons:

  • It has a superior CLI. With it I can create pages, switch versions, autocompile (local server + auto-compilation of changes) and get config information.
  • Using a built-in rake task, I can deploy to my server with an rsync-based command.
  • I prefer the way the extensibility was handled with helpers and filters.
  • I really like the Rules file. It allows you to specify how items get compiled and where they get compiled to.
  • The main author, Denis Defreyne, was very responsive and helpful through both the nanoc discussion forum and IRC.
  • The project is actively developed with an active commit log, version roadmaps and a ticketing system.
  • The opportunity to explore another language (albeit one that has made me run in the past).
  • Above all, nanoc just felt right to me. I tend to go with my instincts and they told me nanoc was the right tool.

Recommendation

If you’re looking to move your project to using a static site generator I’d recommend defining what a solution means to you and backing up from there. There are several worthwhile tools out there. Analyze, research and be sure to give each of your top contenders a whirl. Chances are you will find something you like in each of the tools you evaluate.

Until next time

Thanks to everyone for responding to my message on twitter and specifically to Jeff Forcier for recommending I look into nanoc. If you want to talk more about static site generators with me feel free to ping me on IRC (richleland or in #nanoc) or shoot me an email.