Moving my website to Hugo

Web development can be complex, and for people like me, WordPress hides all that gargantuan complexity behind a pretty U.I. There isn’t much more to do than log in and write. WordPress is convenient that way and I’ve used it for years.

In the early 2000s one had to download source code as a zip file, unzip and upload it to the server and connect a database to it, cross one’s fingers and hope it worked. These days, Cpanel on my server lets me install it with one click, so getting WordPress up and running is fairly easy.

My old WordPress website worked just fine, so why did I move to Hugo, a Static Site Generator? There are some peripheral, not-necessarily-important reasons, but the strongest was the itch. In a post in 2024, I wrote that I want to try out Hugo, and it was this itch that made me want to shift.

If things don’t work out, I may go back to WordPress, so rather than delete it, I have just put it on maintenance mode for now.

Why put WordPress on the bench

My not-necessarily-important reasons are:

1. My website hosts a handful of posts and a single page. Having an entire CMS system dedicated to just a few pages bothers me. Not that any of it ever got in the way, but just the idea that all that tooling exists to serve these few web pages is crazy.

2. WordPress requires constant maintenance. Every time I log in, I have to apply updates to the core software, to plugins and to themes and if I don’t, I’m leaving myself vulnerable to bad actors.

3. Speaking of bad actors, one time, my WordPress website served penis enlargement ads to visitors, because someone injected code into my website. That was embarrassing and scary. It has only happened a couple of times over two decades of WordPress use, but these things leave an impression.

4. I write my posts in Markdown, on a text editor called Emacs. To publish the post, I have to copy and paste the text into WordPress. This in itself is not much of a hassle, but it leaves me with two copies of my post–one on my website and one locally, on my computer.

   No matter how much I try to polish the post, once I have pasted it into WordPress, I find myself making tweaks, which makes my local copy redundant. So I have to download the published post as a markdown file and ¹update my local copy.

5. Backing up WordPress is a mess. What I need are my posts in a clean text format, along with my images in a sensible directory structure. What I get are xml files and database backups, which, to be fair, are efficient if I want to move to another WordPress instance I guess.

As you can see, none of these are really deal-breakers. Also WordPress is Open-source software, which ticks my personal preferences check list.

Why I’m giving Hugo a shot

I guess I’m moving to Hugo, for these reasons:

1. To scratch an itch. For me, there isn’t much more to learn about WordPress unless I want to get into professional web development. I need a simple website that can hold my writing. Hugo has the right learning curve, and that pleases my tinkerer’s heart. It’s going to take me a few years to grok Hugo and I look forward to it.

2. There is little to no maintenance required for the site itself. I may occasionally have to update a theme or update Hugo itself, but that happens locally, on computer. If the site goes down, it wouldn’t be because of the website itself.

3. Since my Hugo site is literally a bunch of HTML and CSS files, (hence the term Static Site) security is easier. No database to inject code into, no PHP to mess around with.

4. Creating new pages is as simple as writing in Markdown and saving it in the website folder. That’s it. Hugo generates the actual HTML files. This is the part about Hugo that I like the most. This very file that I’m writing in becomes the web page you will read.

Making the move

Hugo is an entirely new ecosystem of concepts I have to learn. (Partials? Leaf bundles? What?). It took me most of Sunday evening to wrap my head around just the basics. I have to use a terminal (Yow!) and learn basic Git.

Once I installed Hugo, it took me a little time to understand how the themes interact with the content. I still don’t think I understand it fully, but obviously, I managed to get a site running.

What tripped me up for a long time was getting images to show up in my posts. Eventually I figured it out. For the theme I’m using, the images for posts should go into a folder with the same name as the post itself.

Creating helpers using Emacs

Emacs has a well known package called Ox-Hugo that lets you write in org-mode format and exports the finished text to Hugo-format Markdown, with front-matter in place.

I decided to skip Ox-Hugo because I need to properly understand Hugo first. Maybe once I settle into a predictable workflow, I could experiment with ox-hugo.

For now, I have generated some elisp functions (using ChatGPT) that help me do the following in Emacs:

1. Creating a new markdown file, with TOML front-matter in place, in the Hugo content directory.

2. Linking to other posts using Hugo’s relref format (for relative links)

3. Creating footnotes. I realised² only later that the brilliant Markdown mode in Emacs already offers this, and far more robustly.

4. Inserting images to posts by letting me pick an image from anywhere in my filesystem, then creating a directory with the same name as the post, copying the image into it and only then inserting it into the post. Also – insert YouTube and Vimeo videos.

5. I needed to migrate about 70 posts from my old website into my new one. I tried a WordPress plugin that exports to Hugo format, but it didn’t work too well for me. I don’t yet have the technical skills to understand the structure of the output. So, I simply loaded all the pages into a separate tab on my browser and downloaded them all as Markdown files using a Firefox plugin.

   Then I generated an Elisp function that looped through each of these files, added the TOML front-matter, cleaned up the URLs pointing to the old site, renamed the files to a format I prefer and created folders of the same name (to move image assets into). It mostly worked. I had to use Ripgrep to search through the directory to clean up some URLS and Footnotes, but it didn’t take too long.

Serving the Website

All the Hugo tutorials I have read recommend Git as a way to push files to the server. I understand there are services such as Github and Netlify that can serve the files from the Git repository.

I need to host my website on our co-hosted server, and while the Cpanel there offers Git, I still don’t know enough to figure out a publishing workflow. Until I do, I’m manually FTPing the files onto the server. I realise now that, each time I need to add a post, or make a change, I need to upload the entire website–that is–all of the html and css files onto the server.

For some reason, I had assumed that I only had to upload new posts. In retrospect, uploading the entire site will ensure there are no broken links. I guess I’m still thinking in the dynamic sites paradigm. Uploading the files currently, takes about 10 minutes, and will get longer with each new post I add, so, this is a bummer, but I’m going to stick with it until I figure out how to use Git.

What works and what needs work

I love the novelty of it. I’m glad that I finally did it–I’m now using a static site, generated using an SSG. Whoooo! I definitely feel a sense of accomplishment.

I also love the new workflow. Straight from my Markdown file to your browser. It couldn’t be simpler.

What I need to work on is to understand themes. There are a lot of Hugo themes out there, but applying them is not straightforward. Each theme has slightly differing configurations, which affect the whole site, so I need to back up my content before experimenting with them.

Also, my old WordPress website and theme felt a lot more polished, but I guess I’ll just have to learn HTML, CSS and the Go templating language that Hugo uses, to polish my site over time. After all, that was the point. The itch to switch stemmed from the need to have something to tinker with and learn from.

Well. Now I’ve gone and done it.

Notes