Static Site Generators - a Road to Hexo

Static website generators are nothing new (I've even refactored one to PHP5 in 2007 when working for Spil Games). In the recent years static generators started to gain more traction, because not everything must be dynamic and if something is static, scalability and security are mostly no issue. For simple content websites and blog this is also cost effective, as you do not have to have a database and can host it almost everywhere (sometimes even for free). If the website requires something dynamic (eg. comments), there are always external services (like Disqus).

My Ideal Static Blog Generator

I wanted to find a static blog generator that:

  • support also normal pages
  • has comments integration (Disqus)
  • has Atom feed and sitemap
  • has a decent theme ready to use
  • node.js based is preferred but not required
  • has categories and tags support
  • is not overly bloated and easy to understand
  • has support for code highlighting

If you start to think about static blog generator it is very likely you will first encounter Jekyll. It was used on many big deployments and is very popular (over 11 thousand stars on GitHub). It is written in Ruby which was my first and main objection to use it. I hae used Ruby on Windows some time ago and it had some gotchas. In addition I like to look into the engine itself if necessary and I know Ruby only from one book I've translated several years ago.

A friend of mine recommended me something that is Python based - Pelican. I've used Python actively for over two years now, but in the past I was very proficient with it, so the main issue with Jekyll was definitely not applicable. Pelican has everything I need (highlighting, themes, Atom feed, pages support, Disqus etc.). It ended to be may backup plan I do not find anything similar in my current domain of expertise which is node.js.

In the node.js land I've found several mature static website generators and several others that are in preparation. I've chosen to check two of them:

Docpad looks nice but it is meant mostly for traditional websites and blog support is an addition (as a bunch of plugins). I've installed it, but you must be aware that you may expect some spying. After playing with it for an hour I got the impression it was too complicated for my needs.

Punch was the next one to try out. It was also not meant for blogs initially, but there was a boilerplate. The problem was that it was not working for me in the way i wanted (I was receiving some errors) and the available theme was not what I had in mind.

After failing with static website generators that have blog plugins, I've started to look specifically for node.js static blog generators. I've also found several of them but most of them was too much CoffeeScript or to immature to just grab and use. And then i have found Hexo.


Hexo is a static blog generator with very well written basic theme (works nice on mobile devices). It is minimalistic in nature and have plugins support. It works out of the box and have all elements I mentioned earlier. Templates are using ejs which I know very well. For CSS the default is Stylus where my preference is LESS as it is compatible with standard CSS, but there is a plugin for it. Configuration is in YAML which is also very nice.

Preparations for new blog are mostly related to:

  • editing configuration files (there are two of them, one on site level and one on theme level)
  • tweaking the theme
  • create first post and test it using hexo server
  • generate (hexo generate) and deploy the public/ folder

The Hexo documentation is decent and suffices for beginning the journey. All the preparations (including theme changes) took about two hours. The other two hours I've fought with rsync on Windows to automate the deployment. Hexo has rsync support but using the rsync from Windows is not trivial. More on that in the next post.

The additional bonus of Hexo is that it is easy to make it work as generic website generator which I'm going to use soon.