Hackerman's Hacking Tutorials

The knowledge of anything, since all things have causes, is not acquired or complete unless it is known by its causes. - Avicenna

Jan 31, 2016 - 5 minute read - Comments - Migration to Hugo Not Security

Why Hugo?

As you may have noticed (well no one reads this so I am fine), I have moved from Octopress to Hugo. I have been trying to make this change for a while but due to laziness and some other matters it did not happen. I am going to talk about why I decided on the move and what I did. In then ext post I will talk about my migration from Octopress to Hugo.

Octopress the Bad Parts

  1. Octopress had become so slow. Although I do not have many blog posts, they are usually long and contain images and code. Also it does not support incremental generation which means that every time I wanted to push my blog, I had to re-create the blog from scratch. I could live with this because I only do new posts every once in a while so waiting a couple of minutes before deploying the website is not inconvenient.
  2. My main problem was during content creation. Every time I wanted to look at my changes I had to wait 30 seconds and then refresh the page manually to see the changes. This became very inconvenient. I started creating my posts in a local markdown editor (with preview support) and then copy/pasting it into the actual markdown file and looking at the result. However, modifying posts still took a lot of time and effort.
  3. Octopress was written in Ruby. I am not a developer but I have written Ruby code (some of which are closer in your everyday lives than they appear ;)) but as you can see in my imgpopup plugin post, creating plugins for Octopress was a pain for me.

Octopress the Good Parts

Hafiz the famous ancient Persian poet said "عیب می جمله چو گفتی هنرش نیز بگو" which basically means that you should talk about the strengths [of something] after you have ranted about the problems.

  1. Clean theme: The Octopress classic theme is great. I really like it.
  2. It does what it claims. You can install it using a gem and set up your posts and it is probably good to go. Most probably you will not encounter a bug.
  3. Posts can be written in Markdown.
  4. It has a lot of plugins for everyday use out of the box. There are plugins for code, images, videos and tweets.

Does this mean that Octopress is a bad static website generator? Not really but it did not work for me.

What I Wanted

  1. Be reasonably fast.
  2. Code and image caption plugins. Most static website generators supports code highlight by default but I really like code and image captions. Either it should be supported or I could create my own plugin.
  3. Have the Octopress classic theme or a similar theme.
  4. Allows me to migrate my posts from Octopress. In other words, support writing posts in Markdown. This is supported by almost all static website generators.

I could go to Jekyll and almost everything would work without problems but creating plugins would be a pain. After all Octopress is built on top of Jekyll. Some call it a fancy front-end for Jekyll but I disagree.

I shopped around looking for static website generator and my final choices were Pelican and Hugo.


This post titles "Migrating from Octopress to Pelican" by Jake Vanderplas was really helpful and that was one of the reasons I almost chose Pelican and even modified most of my posts to work in Pelican.

  1. Pelican is reasonably fast. I was amazed after I changed something in my post and saved and the page in browser auto-refreshed with changes within a few seconds.
  2. It is written in Python. Nowadays I write most of my code in Python but creating the plugins were a pain. I fiddled with them for a few days and gave up after I could not create what I wanted.
    • There is a figure with caption plugin called better figures and images.
    • There is no code caption plugin. I tried creating my own but I got lost. The reason was that because the code is not a one liner (it has an opening tag and closing tag with code int between), I had to create a Markdown pre-processor. There is an Include_code plugin that creates a highlighted code block with caption but it only supports pulling from a file. That would not work for me.
  3. Someone has already done it. https://github.com/duilio/pelican-octopress-theme
  4. I only needed to modify some tags but it mostly worked.

Pelican was a really good fit. However, the pains that I had to go through in order to create a codeblock with captions plugin (Markdown preprocessor what?), made me skip this and go for Hugo.


I will talk about why I chose Hugo and the migration in length in the next post. But for now let's see if Hugo is a good fit for my requirements.

  1. It is reasonably fast. Similar to Pelican when I modified a Markdown file, the browser auto-refreshed and I could see the changes in a few seconds.
  2. Hugo had neither. However it supports shortcodes and I could create both in a few minutes. I will talk about what I did and how I did it in the migration post.
  3. Hugo does not have the classic Octopress theme and this was a big weakness compared to Pelican. But as you can see I made my own. It was a good exercise in learning about the inner workings of Hugo and css.
  4. Not only Hugo supports Markdown, it has an import Jekyll module which works for Octopress. It seems like a good number of people have moved to Hugo from Jekyll because there are a good number Jekyll themes ported to Hugo. For a list of Hugo themes you can visit this repo.


Hugo fit my criteria better than Pelican (or any other static website generator that I encountered during my search). It did not have the Octopress classic them but I created my own. In the next blog post I will talk about my migration from Octopress to Hugo.