From Octopress to Hugo

NOTE: work in progress post

I guess it is that time again to update my blogging platform, as chronicled in this post, I have had versions of this site in: Movable Type, Lyceum, Wordpress, Octopress and now Hugo.

Why moving to Hugo from Octopress?

What’s wrong with Octopress?

The simple reason is:

Octopress development has stopped

The last commit on Octopress’ repo was on Feb 9, 2016. The last post from Octopress website itself was the announcement of the upcoming Octopress 3.0 - this was on 2015.

The other reason is: related posts, I just couldn’t get it to work with Octopress. To be honest, this is not Octopress issue. It is the issue with the underlying Jekyll that Octopress is leveraging. Jekyll uses Latent Semantic Indexer (LSI) to calculate related posts, it is encapsulated in classifier-reborn gem. However this gem / method has known not to work for larger number of data set (in my case it’s the 300+ posts), see: this and this as few examples.

Anyway, I really missed this feature as I used to have on WordPress.

Why Hugo?

As opposed to Octopress, Hugo is actively developed.

Another reason is, I am developing with Go now and Hugo is written in Go. This hopefully will give me a good chance at looking at Hugo code base and perhaps contributing in the future.

The steps

Create a new Hugo site

I created a new site following Hugo quick start guide.

Use Octohug to transform your content

At this stage, you could try to simply copy over your content from Octopress’ content directory to Hugo’s content directory and see if this works.

I found that for my case, this almost works, e.g: Hugo build those posts with no issue. However there were a couple of issues that I think is probably unique to my site (might not be relevant to you).

My issue has to do with the fact that my blog used to be a WordPress blog before Octopress. Unfortunately, for some reason the WordPress posts have no date metadata on the front matter. This has never been an issue with Octopress / Jekyll as it can infer the date from the filename. Not so with Hugo.

Luckily I found this Octohug script to help with filling in the date metadata and other transformation or cleanup tasks. Treat the script as a base code, you will need to tweak the script for your own need, here is my version of Octohug script that does the fix ups for this blog.

This took the majority of my time in migrating.

Fixing Issues

Code highlight

Octopress has different code highlight syntax, e.g:

{% highlight ruby %}

{% endhighlight %}

This needs to be translated to:

{{< highlight ruby >}}
{{< /highlight >}}

I don’t have many posts with code, hence I fixed them manually.

Images and image tags

Hugo stores images under static directory, my Octopress blog stores them under files directory.

I chose to use the same files directory structure, but I can’t move them under blog directory - Hugo doesn’t like that.

I then copy the images across:

cp -r files ../passionate-hugo/static

This will copy the images into passionate-hugo/static/files.

Then the image links need to be fixed up, from /blog/files/ to /files/.

The next thing to fix is the image tags themselves.

Octopress image tag is as follows:

{% img /files/image.png %}

That needs to be converted into Hugo’s:

![Example image](/files/image.png)

I didn’t remember how I fixed these tags - most likely I used find and replace with Vim.

More content will be added.