↓Skip to main content

Hugo in Gitlab

Meta

Yesterday I finished shifting this this from Jekyll (hosted in Github) to Hugo (hosted in Gitlab). Some of the work was kind of trivial, for example using Hugo’s Jekyll importer that swallowed all the posts but not the pages.

I dealt with the pages by copying them directly to the content directory and changing their front matter to include the desired URL. For example:

title: Publications
date: '2025-05-13T20:42:38+13:00'
layout: page
url: '/publications/'

After a few tries I settled on the congo theme and had the brilliant idea to install it as a module. I didn’t manage to get it working in Gitlab, despite of playing with the configuration file. Installing the theme by cloning it under themes worked well.

One of the biggest time wasters was getting the right information for setting up my domain in namecheap to point to the pages in Gitlab. The keys generated by Gitlab to create a TXT field in my registrar for domain verification included the full name of the domain, as in luis.apiolaza.net at the end, but Namecheap needed only luis (the subdomain) at the end of the first part of the key. At the end, I needed to include the following pieces under advanced DNS:

Type      Host          Value
A         luis          Gitlab's IP address
CNAME     luis          username.gitlab.io.
TXT       longkey.luis  evenlongerkey

After all that, the site was just working. Some material that was useful to get my head around:

  1. Gitlab’s tutorial on how to setup pages using Hugo.
  2. One bit that tripped me is that once the pages were up the design (CSS) was not working. This was fixed by updating the site config file to update the baseURL to, first, the gitlab.io site and, later, to the custom domain.
  3. GitLab Pages custom domains with the proviso that the way we setup the DNS information might differ from that explanation (see above).
  4. Once everything is connected, every time there is an update one can go to Build/Pipelines to check that everything went well, followed by Deploy/Pages to check where the site is live.

The shift required some typing…