At the start of 2020, I moved from WordPress to Hugo, a static site generator. I’ve finally made the decision to move back to WordPress for a number of reasons.
I chose to try Hugo because I wanted to keep my website simple and do the frontend development myself. With a static site generator (SSG), you can write flat text files in Markdown, which get compiled to static HTML. The allure (for me) is the simplicity: you just write text in a text editor and avoid all the cruft of a web interface. While it was a valuable learning experience, it wasn’t as simple as that.
In order for the SSG to build web pages from your Markdown (MD), you have to build templates in a theme. This requires an understanding of how (in my case) Hugo works. Not only do you have to understand the order in which Hugo nests templates, partials and shortcodes, but also how to use its templating language to manipulate content as well as data from the front matter in your MD files. I built myself a theme that was basic but worked well and didn’t look too bad in the end.
I was able to embed images and add captions in posts, but it was a convoluted process. First, I had to convert the pure MD file to a page bundle, which meant creating a directory with the same name, moving the MD file into it and renaming it “index.md”, then adding a folder called “media”, and putting the images into that. In the front matter, I added the necessary YML fields for each image. Then, using a shortcode I developed, I just placed the image in the appropriate place in the text.
You have to configure/build basic functionality yourself
Bit by bit, I was building functionality that “just works” in WordPress and the further I went, the more I realised there was no way I was going to keep on top of it all. Every time I changed something in the design or built new functionality, I had to re-learn bits of Hugo.
I decided to add comments, which I initially thought I could do without. You can either use something like Disqus, which costs a monthly fee and you can’t self-host, or set up an Isso server. The latter was the option I went for because one of the reasons I like the idea of a SSG was that you store virtually no data on users. Just setting up comments, then, required me to host a Python application, install a NoSQL database, configure a reverse proxy and then adapt my MD archetypes (the template that Hugo uses to create blank content from) to control whether comments are activated or not.
At some point, I wanted to add SEO titles and meta descriptions, as well as various open graph attributes. This was interesting, but is so much easier with a plugin such as Yoast on WordPress. Multilingual is built in to Hugo and surprisingly easy to configure if you know your way around Hugo – but it requires you to edit your templates to output the right HTML header information, having researched how to access the variables that give you this information.
Of course, I could have just used a Hugo theme and been done with it. That way, I would have (theoretically) been able to write my content and refer to the documentation. But things like running an Isso server would still be an issue.
A complex publishing process but a good learning experience overall
The process of publishing required several commands:
- Create a new blank article with Hugo on the command line
- Start writing
- Fire up the Hugo server to preview it
- Add and commit the result to Git
- Push to the server
- Remember I forgot to change “draft: true” to false in the front matter
- Change, add and commit again (with a short commit message)
- Push to origin…
On top of this, I realised my frontend skills aren’t up-to-date. I used to be more on top of HTML, CSS and JS but stopped around 2015. Since then, things have moved on and even making a basic site requires so much overhead. One thing requires another requires another requires another… Luckily, Hugo has built-in support for SASS, which made my life easier; it can also minify your HTML and CSS for production (only). If I’m honest, this was reassuring because I thought it would save me blushes in case anyone had a look at the code!
Learning Hugo was a great educational experience – you quickly realise that SSGs are much more than simple static websites. SSGs are great for outputting web content efficiently, but combined with CDNs and headless setups, they can be very powerful. Building your own forces you to confront some of the challenges: no server-side dynamic content so it has be integrated at the time the HTML is compiled, or pulled in dynamically on the client.
A different type of simplicity
Now, hopefully I can just get my head down and write on my blog without having to scratch my head about where to upload the file and how to edit front matter and embed the image correctly. I’m also hoping not to be faffing around with web technology quite as much – although even maintaining a WP installation on a virtual serve is enough work in itself.