Getting started with Hugo

Introduction #

A few years ago (2010 to be exact) I started a blog which was dedicated to my studies in the networking world (Cisco etc.) and for that I ofcourse used WordPress as everyone did then. I last wrote on there in 2013 and its been sat there ever since.

One of the painpoints of having a WordPress install, especially one which isn’t used anymore and is just kept around for archived content (I still get some traffic to it today) is that you have to maintain it and in the world of CVE exploits this means at the minimum keeping things updated to try and protect against them.

The other thing is that WordPress requires a webserver with at least PHP and a MySQL server running and these alone bump up the requirements either on your own hardware/vps or in hosting costs.

Before I started this blog I had heard of SSG’s however I had never really done anything with them.

When my last renewal came in for the webhosting for the old blog I thought that maybe I should try out exporting the blog to an SSG.

There are plenty of SSGs to choose from, some of the most popular are Jekyll, Hugo (what powers this site) and then some like next.js which are more geared towards React apps than simple blogs/sites.

While there wasn’t a huge amount of content on the old blog there was enough where I didn’t want to manually copy it over and so I thought I would write a post on not only getting started with Hugo but also how to export a WordPress site and import it into Hugo.

Creating a site in Hugo #

Hugo is written in Go however you don’t really need to know/care about that which is nice as although I have used Go in the past I don’t use it enough to be comfortable writing it in any volume.

There is excellent documentation on the Hugo site but I thought I would extract some of the main points here.

In order to create a site you’ll need to install Hugo on your platform of choice as well as installing Git as we’ll be using that as well.

hugo new site quickstart
cd quickstart
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> config.toml
hugo server

For a better overview of what we’ve just run please read the getting started guide here which has an in-depth overview of each command and what it is doing.

Once you have completed these steps you will have an empty Hugo site running on its built-in local server; one of the awesome features of this is that you can leave it running in the background and as you create/update/delete content it will automatically build and refresh your site for you.

Exporting from WordPress #

There are a number of ways that you can export your data from WordPress however I found one of the best (at least for my blog) was to export the data to a Jekyll export first and then use the new hugo import jekyll command to bring the content into Hugo.

For this we’re assuming that you have access to install Plugins on your WordPress install, if you don’t then there are other alternatives you can try.

The plugin we want to install is called Jekyll Exporter and we can see it in the top left of the above screenshot.

Once you have the plugin installed and activated you can carry out your export from the Tools > Export to Jekyll link in the admin panel.

When you run the export there are no options, no selections to make it just a ZIP which is generated and downloaded for you.

Inside the export will be all of your posts, the content in those posts (images etc.) as well as all your drafts/versions (these are ignored later).

Importing to Hugo #

Going back to the basic Hugo site that we created in the earlier step we’re now going to import the data from the Jekyll export that we just did.

Using the hugo import tool will actually create a fully working Hugo site for us however if we want to use the one we created earlier we need to import things into a temporary directory first and then move our content into the site we created.

# Unzip the export we did
unzip jekyll-export.zip -d jekyll-export

# Import the Jekyll content into a temporary site
hugo import jekyll jekyll-export temp

# Copy the posts and content over
cp -Rv temp/content/ quickstart/content/
cp -Rv temp/static/ quickstart/static/

# Remove the temporary files
rm -rf tmp jekyll-export jekyll-export.zip

This is all that is needed, if you now run hugo server from inside your site you will see all your posts.

Caveats #

The importer is not perfect and so I highly suggest you review the content which has been imported. The tool tries to export things in a compatible way however there are some things such as url encoded characters and custom elements like YouTube elements which might need tweaking.

Hosting your new site #

One of the benefits of SSGs is that they can be hosted anywhere pretty easily as once you have compiled the site it is just plain html/css/js and doesn’t need any server-side support from things like PHP or MySQL anymore.

I found one of the easiest options is to use Netlify as they handle everything for you including custom domain support, rebuilding the site as soon as you push to Github as well as SSL support which is almost required these days for good SEO.

They have a documentation page for integrating Hugo with Netlify here so I won’t go into too much detail but I suggest adding a netlify.toml file to your repository and then you don’t even have to go into the settings on Netlify itself.

# netlify.toml

[build]
command = "hugo --gc --minify -b $URL"
publish = "public"

[build.environment]
NODE_ENV = "production"
GO_VERSION = "1.19.4"
TZ = "Europe/Dublin"    # Set to preferred timezone

[context.production.environment]
HUGO_VERSION = "0.109.0"
HUGO_ENV = "production"

[context.deploy-preview.environment]
HUGO_VERSION = "0.109.0"