Moving to Hugo

· Read in about 6 min · (1209 words)

Last weekend I completed the preparations for moving this blog from Wordpress to Hugo. I have been considering this a few times, but never really had the time or energy to go the full length.

Wordpress have served me well for the few years this blog has run, and for most people WP is a great way to get up and running with a blog. There are thousands of themes and plugins available where you can tailor your site to fit your needs and like.

However, this comes with a cost. You need to keep your installation updated, i.e. your plugins, themes, database and WP itself. Security is a big part of this and needs to be taken care of. You’ll need backup and you need to make sure that your backup is available for you when you need it. On top of this you will probably have a monetary cost.

Lately I’ve found that I have had to spend some time each week on updating either the plugins, installation or database and checking security things.

When I had a conversation with a colleague that looked at starting his new blog we looked at Hugo which I had considered before. He chose to go that route with hosting on GitHub pages, and I wanted to have another look at this for my site as well.

I remembered the blog posts my fellow vExpert Christian Mohn wrote when he migrated his site a while ago.

As Christian says, the thought of being static, with plain old files written in Markdown, was compelling. Having my site on GitHub takes care of the backup and with a powerful CDN network combined with the continuous deployment options on many of the available hosting providers I would probably end up with a much faster site.

I considered GitHub pages for a while, but ended up with going the same route as Christian and chose Netlify as my hosting provider.

The setup couldn’t be easier.

  • Create a Netlify account
  • Create a new site in Netlify
  • Connect to your GitHub and select the repository
  • Hit deploy

In a few clicks and some seconds of automatic build and deploy your site is live. Add in continuous deployment and you can have your site build and deploy on each push to GitHub.

My migration

I was prepared for putting in some hours in the migration as Christian mentioned in his posts even though his site has much more content than mine.

Theme

After installing Hugo and getting to know the basics the next step is to choose a theme for your site. I considered a few, but ended up with the Bootstrap premium. Initially I wanted a different theme, but I found that a bit harder to customize. I might go back and choose a different theme in the future, but for now this will do.

I did some theme tweaks to have it the way I (almost) wanted and continued on to migrating my existing WP content.

Migrate existing content

For this I used Exitwp which Christian covers in his post. Basically you use the built-in export functionality in Wordpress to get a xml file which the tool will process and convert each post to markdown files.

I spent some time on cleaning up each and every post, removing whitespace etc (which I probably could leave as-is, but I really hate those syntax warnings in VS code). The most time was spent on fixing the images in my posts. I fixed all the old WP short code stuff and replaced it with the Hugo figure shortcode. I also made two versions of most of the images where I have the smaller one displayed with a link to the full image. I did also run an optimizer on the images to make the files smaller.

I also updated the url in the front matter on the posts so that it would match the new site and I also fixed some of the category/tags stuff which. Other than that I left the content of the posts as-is.

I did rewrite and update some of the pages, i.e. the about page and privacy policy.

Finally I found a site for generating a favicon that my site was missing. After several hours the lack of creativity had me ending up with just my initials.

Deploy to Netlify

After having changed most of my content, fixing images etc it was time for deploying to Netlify.

The initial deployment was ok, but after doing some more theme tweaks things stopped working. After some troubleshooting I saw some errors in deploying the theme through git submodules. I might be out on thin ice on the git technicalities here, but in short what is happening is that with submodules you just have a pointer to the public git repo of the theme you’re using through. When I did changes in developing the site this was fine because I had the submodule downloaded locally, but Netlify will pull the files from git.

I tested a few ways around this, from cloning (which isn’t supported on Netlify) and forking the repo. I could copy out the files, but that would keep me from having updates later on.

After struggling a while with this I came over this article which mentions the ability to have several themes on your site.

The solution proposed is that you will have your chosen theme as a submodule as per the documentation, but every tweak you make will live in it’s own «custom theme». Basically you replicate the file structure for just the individual file you change in your custom theme. Then in the Hugo config you put your custom theme first in the array of themes and this will merge in with the othe® theme(s) you have. Pretty neat!

Go-live

After fixing the theme and pushing my changes to GitHub the last step is to fix my DNS records for the site to go-live on Hugo and Netlify.

Netlify will provide you with a wizard for this, where you get the actual CNAME record you need to use if you have a different registrar than Netlify. SSL is default on with Let’s encrypt so that will also be taken care of.

Summary

I am really exited now that (hopefully) most of the hard work is done with migrating the existing content. From here on I hope that I can spend time on writing content and not updating plugins.

There is still a few things to add, i.e. a search funtion and a RSS feed, but that will hopefully be fixed very soon.

One thing that is missing from the old site and will not be set up in this new is the ability to comment. I almost threw that out when the GDPR madness set in, but I kept it (and was hopefully complaint through some plugins…), but for now I think I’ll leave it although Hugo ships with support for Disqus.

This concludes my migration story so far, if you’re reading this post through www.rudimartinsen.com that would indicate that things was successful.

Hopefully you found it useful. If you have any comments or questions, or if you’ve found something that seems strange after the migration, please reach out on Twitter