· 4 minute read

Learning a blogging platform outside the Wordpress domain has been on my mind for a while. I’ve been working with Wordpress sites as an author, editor or general maintenance man, for ten years now and I felt it was time to expand my horizons.

I researched static site generators and settled on Hugo as a new platform to learn. Aside from learning a new technology, another reason for moving the blog to a static site generator is that my Wordpress sites just seem so slow these days, despite optimising and aggressively caching where I can. Part of the reason is cheap shared hosting but, for personal sites, cheap hosting is fine with me!

Following a steep learning curve, I’ve migrated my music blog The Perfect Twang from Wordpress to Hugo. This post summarises what I’ve learned so far. If you’re looking for a guide on moving from Wordpress to Hugo, I recommend reading posts by Justin Israel and Justin Dunham.

Installation and set up

Installing Hugo on my Mac was the most difficult part of the migration. This is mainly due to my lack of skills with a command line and understanding of Mac permissions! While the Hugo installation instructions are short and clear, I hit permissions problems in Terminal, which took some research to figure out.

Once I resolved these niggles, it was surprisingly easy to get a vanilla site up and running. Win! Next…

Content review

I used Ben Balter’s Wordpress to Jekyll plugin to export my blog posts as markdown files, which contained tags, categories and other metadata. The export included a copy of the /wp-content folder, which contains images or other uploads related to posts and pages.

Reviewing the content is where I spent the bulk of my time. This involved:

  • Fixing instances in post markdown files where symbols had become html entities. These were often apostrophes or quotation marks.
  • Replacing absolute image paths, which contained Wordpress’ /wp-content/uploads/etc, to relative paths to Hugo’s /static directory.
  • Understanding where to store images and other content files referenced by posts. (There’s extensive discussion on GitHub.) I settled on recreating Wordpress’ uploads structure of /year/month/myimage.jpg under my Hugo site’s /static/media directory.
  • Understanding how to recreate Wordpress’ permalink structure via Hugo’s config file settings to avoid having to implement any URL redirection or risk losing PageRank.

Theme and design

There’s plenty of themes available for Hugo sites. I chose the Icarus theme by Zhang Ruipeng and Digitalcraftsman for two reasons:

  • You can include featured images with posts (known as ‘banners’ in Icarus).
  • There’s a consistent-looking archives page that includes featured images.

I customised the theme with an override stylesheet to improve the following aspects:

  • Contrast in the typography to meet WCAG level AA.
  • Display of navigation on small screens, particularly at 400px wide.
  • Display of post titles in archive pages on small screens.

There’s still work to do to make the site theme fully compliant with WCAG level AA but the major elements now pass.


When the site is ready on your local computer, you type hugo in the command line to generate all the site files in the /public directory. This directory is then uploaded to the web server.

Whenever you write a new post, you need to regenerate the site and upload the entire directory of site files to your web server. My Perfect Twang blog of, to date, 20-something posts is 11mb when compiled in Hugo. Via my Virgin Media broadband connection to DreamHost, this takes about 20 mins to upload via FTP. Already, uploading by FTP has become a timesink, particularly when making small changes such as fixing a typo or publishing a new post.

So, next on my Hugo to-do list is to find a more efficient way to track and deploy changes to the live web server.


I’m happy with Hugo in this area. With no queries or round trip to a database like Wordpress requires (Hugo sites are simple, static html pages) there’s a significant improvement. The following table compares performance of the home page before and after the move to Hugo:

Performance measurement Before (Wordpress) After (Hugo)
Load time 1.33s 703ms
Requests 65 28
Pingdom performance grade 69/100 86/100
Page size 1.2mb 727kb
YSlow grade C B
YSlow performance score 78 82
comments powered by Disqus