I’ve long been frustrated with wordpress as the way I post content on my blog:

  • It is bloated and slow to load pages.
  • Requires an SQL server for content which is mostly static.
  • I find the editor unintuitive.
  • Code samples never quite displayed correctly.

I’ve been looking at Hugo for a while now as I love the idea of static site generator, but everytime in the past I tried to switch to it in the past but I was frustrated by the export to hugo plugin for wordpress being broken.

This weekend I decided to take another crack at doing the switch and thankfully found this wonderful blog post by Chris Ferdinandi explaining that the Jekyll exporter will allow us to export our content and get it to work in Hugo!

So I installed the export to Jekyll plugin, exported my site, and got to work. The Jekyll exporter gives you just the content of your site, which in my case boiled down to a folder for my blog, the life log page where I keep all the happenings I’ve been doing in my career, and a wp-content folder with all the images and pdfs that I’ve shared on the site previously.

To pull these over in Hugo I first downloaded the hugo from the website https://gohugo.io.

Next I created a new site with:

mkdir neilhenning.dev
cd neilhenning.dev
hugo new site .

This just creates a default site ready to take my content. Hugo keeps all the pages in the ‘content’ folder, and all the images and pdfs in the ‘static’ folder. So I moved all my blogs over into content, all my images and pdfs into static, and now I need to find a theme I like. Hugo has tons of themes. I wanted a minimal, fast and responsive theme, so I narrowed down to only those tagged ‘Minimal’, and then found a theme called Terminal by Radek Kozieł that was really simple and clean. I didn’t like everything about the theme, but I liked the fact the theme was clean enough that I’d be able to add a static/style.css to override the few things I wanted to change.

Since I am tracking my site in git, I used this point to track what I had in git, and add the submodule for the terminal repository:

git init .
git commit -am "Heyo, gaia?"
git submodule add https://github.com/panr/hugo-theme-terminal.git themes/terminal

And then edited my config.toml using the example site from the terminal as my default.

I host my websites with gandi, who require the website when tracked with git to be in the htdocs folder, so the first addition to my config was to add:

publishDir = "htdocs"

This just instructs Hugo that when you build the website to place all the built content in the htdocs folder instead of the default.

Now felt like a good time to check how my site was going, and so I ran the local server command to see how it looked:

hugo server

This hosts a website at //localhost:1313/ that you can view in your browser. I loaded it up in Safari, and heyo! My site displayed. As soon as I went into any of the content I started to notice some problems though.

For instance all the images were not pointing at the wp-content folder that my site had, they were instead being routed through some weird wordpress domain prior to loading from my site. To get this to work I did the incredibly annoying thing of searching for <img tags and replacing them with the built-in image shortcodes that the terminal theme uses.

I went through all the content, pointed it at the /wp-content/uploads/* folder of the content I had pulled over from wordpress.

I next wanted to ensure that all the links to my original site on wordpress would be correctly redirected to my new hugo-built site. I have a lot of popular incoming links that people use regularly, and so to have these suddenly 404 seemed terrible. I first remapped all the permalink: to aliases: (not sure why I needed this, but permalink definitely did not work…) and then I tried to follow the links as they would have been incoming from my original wordpress - and it didn’t work. I don’t exactly remember why I decided to try this, but I noticed that all the blogs that were exported by wordpress began with the date, then the original title of the blog. So I decided to remove the date from the .md, retried the link in my browser, and voila the original links worked! I have zero idea why this worked, but I then ran over all the other blogs and removed the dates to ensure the original links would work.

Now my site was basically done, the links worked, the images and pdfs were all avoiding the weird wordpress redirects, and I only had to mess with the theme itself. The minor few things I disliked with the theme were that the content was not centered, so I found that the class was called ‘container’, and I decided to center it and make the border which previously only appeared on the right, to appear on the left too:

.container {
  border-left: 1px solid hsla(0,0%,100%,.1);
  margin: 0 auto;
}

The second thing I disliked was the colour used. Luckily the theme makes used of a variant --accent to choose the single colour used in the theme:

:root {
  --accent: #BF76EC;
}

I remapped this to a purple colour that I’ve used in other forms, and noticed that everything but the dates on the posts to the new colour. It seems because the dates use a slightly opaque colour it was specified separately, so I decided to change that colour to use the variable --accent too, which unified the colour across the theme.

.post-meta {
  color: var(--accent);
}

And that is it! My blog was ported over to Hugo, in a simple and fast theme that I liked, and I was finally out of the clutches of wordpress. A few people reached out to me and asked that I write up how I did my porting so they could follow suit - so hopefully this rough guide can help a few of you!