Part of the reason I never get these blogs off the ground is the grotesque user experience of static site infrastructure. Hugo is not a tool I enjoy using, but I feel somewhat forced to stick with it for compatibility reasons. I’ve tried a few alternatives, but they seem to either lie in the same niche as Hugo, or deviate too far down the extreme path of being purely for documentation.

Putting content up via Codeberg seemed neat at first, but the page hosting mechanism of Codeberg turned out to be a bit limiting and my idea of splitting the back-end code from the content hosting was just adding extra steps. Single-sourcing everything via GitLab is fine, I just have to learn to tolerate their hideous UI, and get comfortable with diving through a dozen pages of documentation to find out basic details like “what DNS configuration do I need to make custom domain names work”.

Since a lot of the documentation I found online related to this setup (GitLab Pages + Namecheap DNS) was incorrect, here is what worked for me after a couple of days of furrowed brows:

  • Enable GitLab Pages (Deploy -> Pages)
  • Enable “Use a unique domain” (not strictly necessary, but fixed some weirdness I saw related to the Hugo theme BaseURL setting)
  • Set up a new domain (“New Domain” -> enter the domain name, including any subdomain component)
  • Insert the verification TXT record into your DNS twice - once exactly as provided in the GitLab Pages setup, another time with the subdomain component appended at the end of the host string (in my case, this made the host part of the second record “_gitlab-pages-verification-code.blog”)
  • Set an ALIAS record as per the instructions on the GitLab Pages setup steps
  • Wait some time to check that it works (24 hours - could be less, but best not to assume it should be done before this)
  • If the page formatting looks broken, check using the standard GitLab Pages link (i.e. not using the custom domain) - if access route looks OK while the other does not, the culprit is probably the BaseURL setting in the Hugo config

These instructions are an amalgamation of the official GitLab docs and a knowledgebase article from Namecheap. The GitLab instructions don’t provide the correct guidance about TXT records when using Namecheap, while the Namecheap instructions include an A record and CNAME in place of the ALIAS record. Following the GitLab instructions definitely didn’t work for me, and I didn’t have any quick success with the Namecheap instructions either - though that could have been a result of my impatience rather than the instructions actually being flawed. Either way, that fight is now concluded, so I can go off in search of a new one.