Migration to Hugo 🦸

You might have realized that the visuals of this website have slightly changed 😉. This is actually not “only” a theme change. It went along with a big change under the hood: the migration to Hugo.

This was a rather big step that involved a lot of work for me. But it was worth it.

Let me elaborate.

Problems with Wordpress

The biggest issue was the CMS I was using before: Wordpress. Being the most popular CMS in the whole world wide web, I thought it would be the right tool for me and Flutter Clutter. Turns out: it wasn’t. It might be a good system for other people, but it’s not for me. And I don’t recommend it for anyone with even the slightest development skills.

Updates

One major problem is that basically everytime you open up the admin console, you are presented with at least one badge telling you it’s time to update either a plugin or a theme or PHP or even Wordpress itself.

The greatest fear in this context is: you don’t know how long it will keep working if you don’t update, but you also don’t know if something breaks if you do update because some plugin would lack compatibility with a newer version of anything else.

Also, if you don’t update, there’s a higher chance of exploits being used on your website.

Plugins

“Then why do you use plugins? 🤷” a non-wordpress-user might ask.
Good question actually. That’s because Wordpress with its basic configuration is not sufficient for a little more sophisticated blog.

You need plugins for every tiny task:

• Cookie consent banner
• Decent looking elements like galleries etc.
• “Related posts” section underneath every post
• Decent database backup
• “Advanced” media library for better image support
• …

On top of that: most of the plugins are community-made. There is a motley bunch of unmaintained old plugins, ones that are decent but have an annoying freemium plan and those who are actually good but you don’t find them because the rating system does not really show it.

WYSIWYG Editor online

But what is supposed to be your main task when you are having a blog? Well, hopefully it’s actually blogging. However, you can barely do this with the tools which you have at your disposal, as your only viable option is to use the online editor of Wordpress, which is basically a wannabe Microsoft Word combining all the issues from WYSIWYG ("Why does everything move if I change something here?") with web editor issues ("Oh no, the browser has closed. All my unsaved work is lost").

An example: Effectively, I could not use it in my Google Chrome browser. There is this auto save feature which regularly saves your progress when you are writing an article. However, in Google Chrome, it had a bug that sometimes it got stuck saving. So when you notice it got stuck, you had to copy everything you have written so far (btw: no CTRL + A; CRTL + C possible), reload the page and paste it again.

This is very ineffective and annoying. It makes you check every few minutes if it got stuck again which leaves you less focused on the writing.

Conversions not possible in “hidden” mode

When you are working on your blog, not actually blogging, but e. g. updating plugins or configuring your layout or your site structure, you are unable to tell the system: “Oh, I am in draft mode, please don’t immediately publish my changes”.

On top of that, some of the changes are “irreversible” or at least not reversible without a backup.

Ultimately, this leads (at least for me) to an unnecessary anxiety about making a change.

It's not “yours”

Most of the articles I have written, have consumed a significant amount of time. Nevertheless, in the case of Wordpress, I never had the feeling, I am producing something sustainable, which I could keep for myself. Instead, I have entered it into the predefined editor fields and hoped that it was stored in a well-strcutured manner (spoiler alert: it’s not).

I have always felt like putting my thoughts into a black box and hoping for the best.

Google searches

Whenever you try to google a certain topic (e. g. “how to embed a single JS file in a wordpress page”) you are often presented with many ugly-looking options which also often involve plugins. If the results you get don’t mention for which Wordpress version the problem was solved, then good luck.

Server + DB maintenance

Wordpress offers two ways of using it: self hosted or as a service. Unfortunately, the pricing plans for Wordpress as a service are rather expensive. If you want to be able to use plugins, you have to pay at least 25 € per month (with annual pay).

The other option is hosting it yourself. Depending on your traffic, you’ll have to pay for the server nonetheless. Also, depending on your hosting provider, you might be faced with the glorious task of keeping the system (PHP, Nginx or Apache, Database) updated. This is something you usually don’t want to do.

Sometimes, without an obvious reason, the database service had ended. Visitors told me about the page being unavailable which left me with the task of nervously restarting the database, hoping it will fix the issue.

Black box

In general, the whole system feels like a black box which you are not in control of. Instead, you the system controls you. It makes you feel like you always have to keep an eye of the CMS, instead of mostly focussing on creating new content. If you don’t, you might end up with a broken system.

Spam

Speaking of a lack of control: It has always been very important for me to let the blog visitors write their thoughts and comments underneath my articles. This is the most honest feedback I can get. This privilege comes at a high price: tons of spam. I really mean it. I am only hosting a niche blog but I got more than 100 spam comments per week (already filtered!).

The problem is: I had to have a look at every comment because I wanted to accept the real ones. That took up a lot of time. There are some plugins and services (e. g. Akismet) to get around this, but I feel like most of the bots are specialized on Wordpress pages because they are so popular.

Vulnerability

Not only spam bots have been very active. In the webserver logs, I have also seen many suspicious requests which scanned the system for vulnerabilities. This was also a constant fear: when will my blog be big enough that it’s worth the effort of an actual DDoS attack or even worse: somebody making use of zero day exploit to take over my website and delete valuable content. The list of these is actually very long.

Advantages of Hugo

That was a overview of the issues I had with Wordpress. However, is the new CMS really that better? Or is it only the honeymoon phase in which it’s perceived to be better while in the long run it shows the same issues as the old one?

Well, let’s have a closer look.

Speed / Performance

One general note for those of you who don’t know Hugo: it’s a SSG (Static Site Generator). The difference between this and a full-blown CMS like Wordpress is quite simple: there is no backend involved. Instead, the whole page tree is generated at build-time. This page-tree could be compressed as a zip file and sent to someone else. When the person opens it up and launches it, he will see exactly the same content you saw before you zipped it.

This has a major advantage: because the request point directly towards the pre-generated HTML files, there is no logic that slows everything down. No database whose queries become the weakest link in the chain. Everything served exactly “as it is”.

The performance gains are tremendous. This blog is 3-4 times faster than the old version that was running on Wordpress. And this speed is constant because there is no database server involved that slows down when there is a high load.

Full control

Another very great thing about Hugo is that I always have the feeling of being in control. There is no magic backend that does not let me have a look into its logic. There are only files which are generated. And all of the files are editable.

Security

Since there are no server-side functionality, the classic attack options like SQL injections, CSRF, Session hijacking, Remote code execution and many others are not possible.

Git / Version control

Even if someone somehow gains access to the server and steals everything and then shuts down the server, it’s not a big deal. Since everything file based, it’s under version control and I can go back to a previous state at any given time.

Also, if there is an error in the live blog, I can just go back to a working state via git and take my time to resolve the issue.

No dependency hell

Especially in the Javascript world, there is a very high server-side dependency on (npm) packages. There was once an incident where a package consisting of 11 lines of code was removed from npm, resulting in massive failures throughout the web.

Dependencies require maintenance. Maintenance takes time. Time is needed to write articles and should not be wasted for maintenance tasks.

Even if you come back to your Hugo project after a year, nothing has changed. Everything will still work. No need to update anything.

Deployment

The deployment is also very straight forward. It basically only takes the build command (hugo) with one or two flags telling it to minify the content. This makes the deployment very fast.

This means that if there is a time criticality because of a bug or because an article needs to be released immediately, it’s not a big deal since the deployment is a matter of seconds.

Change things calmly

Whenever I change something that is not content related, I can take my time. I make the changes locally and test as long as I need to. Whenever I feel like I have tested enough and think that everything’s fine, I deploy the changes.

If afterwards I reckon something is broken, I just revert the code, fix it and deploy again.

This is completely different way of working than it was before.

Write markdown / Focus on the content

Instead of trying to understand why the UI of my CMS has changed since the last time I had to update, when using Hugo, I can focus on the content.

Once everything is set up, I just write my content in markdown and never have to worry about structural changes again if I don’t want to.

Challenges

Of course, like any migration, this migration was not performed without any obstacles.

Migration of the existing content

I think the biggest challenge I was facing was the migration of the existing Wordpress content. Of course I didn’t want to lose all the texts I had written, which are an essence of many hours of thought work.

I have browsed the web for tools that automate this migration process. However, none of the tools I found, worked as expected. Some were outdated and did not work with Python 3, others seemed to have problems with the raw XML export from Wordpress. I can not tell if the format has changed or the file size was too big. In any case, I ended up writing my own migration tool. I will publish this as open source later. Maybe someone else can make good use of it.

Maintaining SEO (link structure)

With all the anticipation about the change, I didn’t want the change to have a negative impact on SEO. Unfortunately, Wordpress has not generated a very clean URL structure. That’s why I had to manually adapt a lot of things.

Understanding Hugo

After only about 15 - 20 hours of usage, I am still a greenhorn in terms of Hugo. In spite of its decent documentation, it still has a rather steep learning curve. Especially if you’re like me and want to fully understand things before using them. However, it was lot of fun learning it. I had no prior knowledge in SSG whatsoever so this may have slowed down my learning progress.

Conclusion

All in all, I have certainly invested more than 20 hours into the migration. I can already say, though, that it was definitely worth it. I feel a lot better with a system that I understand (to a certain degree).