Back story

I don’t have time to be a web developer.

I was lucky enough to get into building websites as a kid, before many people had an internet connection at home and before the phrase “Web Developer” really existed.

In those early days I was using simple HTML with inline formatting. I actually remember CSS coming in and making things instantly more complicated, while opening up significantly greater possibilities.
I built things with PHP and MySQL, but I never got round to caring about javascript.

Since then, many web technologies have come and gone. The websites we use today are significantly more complicated than the ones I started out building.

At this stage I don’t have time to learn and understand all of the required technologies. My life is already too busy. I just want something to work out of the box so I can get on with my life. Maybe even enjoy the weekends.

I’ve used Wordpress for years.

For a while I used a content management system (CMS) called CMSimple, but later I switched to the most widely used CMS, Wordpress. I’ve been using these until now for my two main websites, academic.bancey.com and tabs.bancey.com. As long as you can find a suitable Wordpress template there isn’t a lot of coding that you need to do to get a website or blog up and running.

I was reasonably happy with the templates on my sites and mostly was able to get the site layout to behave as I needed. It wasn’t always perfect but it got the job done.

Now it’s time to use something else.

Recently, my shared hosting provider was acquired by a larger company and their attempts to migrate my site automatically to the new systems failed. So I was told that I’d have to migrate it myself or face imminent site deletion.

I could have simply switched to a new host for my Wordpress site, but instead I took this as an opportunity to look for a different way of doing things.

Hugo static site generator

I’ve switched to Hugo.

A recent trend in web development seems to be the use of static site generators, such as Jekyll, Middleman and Hugo. I won’t go into the details here, but there are a number of advantages over other approaches.

Due to it’s promised ability to use Org files as well as the usual Markdown as an input format, I set about migrating my site to Hugo, which is based on the language Go.

Hosting a Hugo site on GitLab Pages.

A really cool feature of site generators is that you can keep everything as a git project, put it in a GitHub or GitLab repository, then using an Action (or Pipeline) GitHub or GitLab will generate the public site files and host them for you on Pages. For me this provides a great way to push site updates, utilize version control and negate the need to pay for shared hosting.

GitLab and GitHub even provide project templates for you to get started.

Currently, GitHub free accounts only allow Pages hosting for public repos. I don’t really want all my source to be public, so I went with GitLab. I did try it on GitHub too though, and it worked just as well.

Setup

Exporting data from Wordpress.

The first thing I needed to do was to export the Wordpress site to markdown. There are a number of Wordpress plugins to do that, but I didn’t have a great deal od success. In fact, I don’t even know which of the plugins I tried was the one that I finally used the exported data from! The markdown files it generated were not at all correct and I ended up doing a lot of manual editing of the markdown files. In particular, I had to fix many of the URL and image tags. It was a lot easier than starting from scratch, but not exactly automatic to say the least!

Starting a new Hugo site

Option 1: Using a GitLab template.

Within GitLab you can create a new project from a template. Choose the Hugo site template. It generates a new Hugo site and sets up the required CLI YAML file that runs a pipeline to build the static site and hosts it as a Page. You can then clone this site to your local machine using git.

This method also applies to GitHub. In the case of GitHub, instead of a Pipeline we need an Action. This is also generated by the template site.

Option 2: Starting a new Hugo site locally.

In the case of both GitLab and GitHub,

Hugo build and hugo server

Before pushing your local changes to the remote repo, you can run a local hugo server with the command hugo server. This creates a temporary version of the site that runs on localhost.

You can also build the /public/ folder, which contains the static site files, but if you are using a GitLab pipeline this is unnecessary. The pipeline will do this build step for you and in fact you should include /public/ in your .gitignore file so that it isn’t included in the git project source code.

Publishing

Push to git

Pushing to the remote repo should trigger the pipeline to build the site again.
You then typically wait less than one minute for the pipeline to complete, and if there are no issues your site should be accessible.

Set to custom domain.

You can follow instructions on GitLab to set up a custom domain name. This involves modifying the DNS settings through the control panel on your domain name provider’s website. In my case this was very easy.

My issues with Hugo

First the CSS file wasn’t being found and then internal links broke

Hugo seems to have a problem running on the GitLab pages address such as https://<user>.gitlab.io/<project>/ and prefers to be on https://<user>.gitlab.io instead. I guess it’s intended for people to run a single Pages project as a user bio site or something. In the settings you can tell GitLab to use the user address for a specific project. But that doesn’t help if you need to run two different projects as Pages. I have two sites that I want to run.

Unfortunately, this means that the URLs of the sites were somewhat messed up. I set baseURL = https://simonbance.gitlab.io/academic/ and through a painful process of elimination I worked out that I needed to modify the menu links in the config.yml file to include the path to the project,

e.g.

baseURL: "https://simonbance.gitlab.io/academic/"
canonifyurls: true
relativeURLs: false
menu:
	main:
		- identifier: categories
		  name: categories
		  url: /academic/categories/
		  weight: 10

However, the “Next Page »” link at the bottom of the page continued to point to the wrong address, and clearly this hack was likely to break down at a later stage, perhaps when pointing to my custom domain.

I also tried this with GitHub pages and faced the same roadblocks.

The whole problem was only truly solved after I set up my custom domain for academic.bancey.com. After this, the following settings made everthing work ok:

baseURL: "https://academic.bancey.com"
canonifyurls: true
relativeURLs: false
menu:
	main:
		- identifier: categories
		  name: categories
		  url: /categories/
		  weight: 10

It seems that other Hugo/GitLab/GitHub users are experiencing the same issue. Although it’s not entirely clear, this post here provides the answer.

If, like me, you intend to host multiple Hugo sites on GitLab (or GitHub) Pages using custom domains, everything will eventually work fine. But for those who don’t want to use custom domains, internal links will remain inaccesible unless they set the project URL to https://<user>.gitlab.io. User onedrawingperday explains how to do that on this thread.

It took me many hours of head scratching to figure all of this out and almost caused me to give up on Hugo a number of times.

Conclusions

Is Hugo good to go straight out of the box?

If you are lucky you can get a site out of the box using Hugo. But in most situations you will need to do some customization to get it how you need. In my case I tried to keep things as simple as possible and found themes that had relatively complete documentation and that I didn’t think I would need to modify much.

Unfortunately, when the site started behaving strangely there was sometimes no clear indication of the problem. In the end, most of these issues were related to the GitLab (and GitHub) hosting address issue that I finally resolved. But in the meantime I ended up creating multiple sites, starting fresh each time, because there was no way to determine the source of the problem. It wasted a lot of time.

Do I recommend Hugo?

Although I haven’t had time to try out any of the other static site generators for comparison, I feel that now I have overcome the initial problems I will enjoy using Hugo. I would recommend that you try it for yourself before commiting to use it for your main website.