Moving from Jekyll to Hugo

Amusingly enough, one of the main reasons I’m moving to Hugo is that I can’t seem to get jekyll running again and I had a few things I wanted to publish. So naturally, a migration post is necessary instead of what I was actually going to do.

One of the main benefits of having a static site is that:

• No databases.
• Cheap/free to host.
• No concern about having to upgrade backend software.
• Having all content version controlled and backed up.
• Lower maintenance cost.

However, in the case of jekyll, the last is not quite true.

So on to pick a new static site generator. For my purposes, all of the functionality is roughly the same from the top 10 generators: jekyll, gitbook, octopress, hexo, hugo, pelican, brunch, and middleman. My only decision filter is “will it ever break”? So with that, the language must be Golang and the top was Hugo.

Transition

The transition was fairly straightforward for the blog and took about an hour of reading and 3 hours of fixing post formatting.

There is a similar mapping between the two systems. Hugo uses layouts/partials while Jekyll has them under _includes.

The steps:

• Import jekyll to hugo

• hugo import jekyll ../tjheeta.github.io tjheeta-hugo
  

• Find a theme from http://themes.gohugo.io/

• Modify the config.yaml to something that resembles what you need.

• Edit all the custom links. post_url needs to be changed to the format {{ < ref "post/yourpost.md" >}} . In some cases, the jekyll date was off-by-one for some reason.

• Change the plugins to shortcodes. I had one mermaid plugin for graphs and charts and that was the trickiest part. Essentially, I had gotten it right, but in some cases Hugo needs a restart and in some cases it does not. For shortcodes and overriding layouts from themes, it seems to need a kick. The mermaid shortcode ended up being:

  $ cat layouts/shortcodes/theshortcode.html
  <script src="/js/theshortcode.full.min.js"></script>
  <div class="theshortcode">
  {{  .Inner  }}
  </div>
  

• Aliases. For some reason my jekyll blog ended in .html, so those need redirects to be added in the page frontmatter.

Conclusion

Time: Took about 4 hours.

Breaking changes:

• No table of contents in markdown. Had to add that back the table of contents with the correct anchors with html and then enable the plainIDAnchors on the markdown generator.
• Disqus comments need to be remapped, but it’s just not worth the effort.
  

New cool stuff:

• Pagination
• Tags
• More readable

All in all, a good experience and I’m hoping hugo doesn’t break in the future.