I’ve been using crotal for two years but today I decided to migrate this blog to Hugo. Why? There are several reasons.

This blog was on crotal 0.6 but the rss feed didn’t really work in some cases (i.e., code listings). After upgrading to the latest version at that point (0.9.7) it turned out that crotal was no longer backward compatible because the template engine had changed from Jinja2 to Mako. There was also another bug, but that one has been fixed very quickly. So I had to invest time one way or the other and there are more things that annoy me. Crotal is barely documented, and the official homepage is currently not reachable. Moreover, crotal is still on python2 and there are no indications that this will ever change. Finally, I always had to fiddle around with virtualenvs in order to have the right version of the dependencies. This point isn’t due to crotal rather than the python ecosystem, but that doesn’t make things better.

As you can see, there are several reasons to drop crotal. But why is Hugo better? There are two main points why opted for Hugo: it is under active development and the documentation is pretty extensive. More than that, there are plenty of templates available and most of them are documented. Hugo is very easy to install, binaries are available for many popular platforms and site generation is very fast.

First steps with hugo

Creating a new site with hugo can be accomplished in a matter of minutes. A step-by-step guide is included in the documentation. Choosing a template took quiet a long time but finally I’ve choosen the Hikari theme. It provides most of the things that I wanted to have. Especially code listings, responsive design, and disqus support. Unfortunately, it lacks an overview site for categories and there is no search bar but I might add these features at some point.

The rest of this post will explain some of the steps that are necessary if you want to migrate your site from crotal to hugo.

After creating a new site with hugo new site path/to/site, your directory structure looks like this:

devmartin/
├── archetypes
├── config.toml
├── content
├── data
├── layouts
└── static

The content of your site has to be placed in the contend folder (..not really surprising, is it?) You can copy over your old crotal content to this folder. But this might not be enough, depending on the structure of the meta data in your posts. For example an old post might looks like this:

---
title: "Print from evince doesn't work after changing credentials"
date: 2015-08-18 21:29
categories: linux
slug: Print-from-evince-doesn't-work-after-changing-credentials
---
...

For some reasons, hugo doesn’t like this format, especially the date and categories entries have to be modified. After changing the categories value to a list and dropping the time part of the date, hugo server built the site without complains.

date: 2015-08-18
categories: ['linux']

Keeping old links alive

The URL design can be configured in the config.toml:

[Permalinks]
    post = "/blog/:year/:month/:slug/"

Unfortunately, hugos default URLs differ from the my existing URLs. An already existing URL may looks like this:

/blog/2015/08/Print-from-evince-doesn't-work-after-changing-credentials

but the URL generated by hugo look like this:

/blog/2015/08/print-from-evince-doesnt-work-after-changing-credentials/

Imho this is a design flaw in crotal, because most popular blogging applications like octopress, wordpress etc. use the second version for their urls as default value. Moreover, using only lowercase letters and omitting special characters lowers the probability that links break when they are shared somewhere.

However, in order to keep my old style links available, I created a redirect for the existing posts in the .htaccess which looks as follows:

Redirect 301 /old/Path /new/path

Last thing I changed was the name for the rss feed. The default name is index.xml, you can change it in the config.toml by adding this entry:

RSSUri = "rss.xml"

If you haven’t subscribed my rss feed yet, feel free to do it now. You can find the old and new address in the sidebar :)