Yeah, I still remember that I was actually blogging at one point of time 😂 This is actually the fourth time I’m getting started with this - and actually the first time when I have a place to do English blog posts properly. More than two years passed since my last post, and I’ve felt that this needs to change now. But obviously, before that - not surprisingly as an engineer - I just had to rework everything 😉 Based on this, the blog got a new stack, replacing Hexo with Hugo. Continue reading if you want to see why and how this happened.

Blogging always gave me plenty of good reasons to spend incredible amounts of time with web development 😂 I’ve started to do this way back in 2006, still in highschool. I only had minimal web skills by the time. I used the good old (now defunct) Freeblog platform, which was kind of popular by the time in Hungary. (Think about Blogger.com’s Hungarian version.) In 2012, Freeblog started to give things up, and I was already much better prepared, so I moved the site to WordPress, which handled things quite nicely. Only until 2016, though, because (again, knowing much more than before), I realized that don’t quite like WP anymore for my own blog. That was mostly because while I generally enjoyed working with WordPress, I thought that most of its advantages are simply not worth it if you write alone, not in a team. But it also brings in a lot of hassle:

• You have to keep plugins up-to-date.
• You need a decent hosting (with PHP, MySQL and whatnot).
• Because it’s dynamic, it’s always going to be a nice target for attacks. (Especially if it’s as popular as WordPress is.)

…so, a lot of extra work. So I decided to try static generators for a change, where a more simple hosting is perfectly OK. After testing this and that, I switched to Hexo, which seemed to be a good option at the time, and for hosting it, I managed to set up an AWS S3 + Cloudfront-based setup, which provided super decent performance.

But the satisfaction with this setup did not last long. One of the problems was, that with the jump to static site generators, I lost the ability to blog from all my computers. That was because it still wasn’t under version control (it was around that time when GitHub made private repos free for everyone, and I didn’t want to use anything else). Also, Hexo was a pain to set up everywhere. In this period, most of the time I could allocate to writing was during commute, so this was a huge minus for me. A few months ago, I managed to solve this with fixing the setup, so the blog got a proper repo, and I implemented the building + uploading to S3 as GitHub Actions. With this, I even managed to give myself a way to test my modifications on a separate sandbox environment: any PR I open automatically gives me a link to the new version, so even comparing them is possible. It was when I was working with the GitHub actions that I realized how crappy Hexo really is for me:

• The documentation is just not good enough, sometimes you can extract more information from the Disqus thread under the doc page than from the doc page itself.
• With Hexo, you simply can’t create a proper multilanguage blog. I have a lot of colleagues who do not speak Hungarian, and I would love to show them my blog, but with Hexo, it’s just not possible. OK, I could move things to other platforms like Medium (I already did a test ride with that), but I would much rather keep my more personal writing in a single place that I control.
• Building the site with Hexo is just way too slow. Even with my site, it took 30-40 seconds to get the static content.

If I remember correctly, my colleague Gábor Boros recommended Hugo, which ended up being the platform to switch to. Hugo supports multilanguage, it has good documentation, and it also has a nice community, which can come really handy especially if you start to migrate things… And the speed, too, is excellent: the Go-based Hugo leaves the Node.js-based Hexo in the dust, as it builds my static content in half second, compared to Hexo’s 30-40.

Anyway, such a migration is always a major pain. It will mess with the content, the look and everything in between… Finally, I managed to get it done with the following workflow:

1. Start to build the new blog from scratch, config it similarly to the previous system as much as you can, and try to set up the new features you would like to use.

   In my case, the hard part was understanding how Hugo does permalinks. It became obvious pretty early that I can’t exactly match how Hexo did it, but this would mean to loose the existing URLs! This is a major SEO fail, especially because my AWS setup does not give an easy way to set up redirects. (Not that I have such amounts of traffic and ranking that I have to worry about this, but still…) The other hard part was getting the multilanguage config right, along with the taxonomies, as the tags are also localized.

2. Test multiple themes, check which you can use.

   In such a complex migration, it’s not a fantastic idea to write a theme as well - you will have enough problems even without that, so it’s better to avoid if you can. But this doesn’t mean you can go with any random theme: you need to be able to alter it to your needs. My choice was Meme, because the layout was pretty much what I wanted (I like distraction-free, text centric stuff), and it gives a lot of options and some cool tricks (eg. dark mode) as well. Also, in the sample config, it contained some tips on how to set up the multilanguage, which was very important, as finding such samples was not trivial. But before I settled with Meme, I had to test 4 other and start tweaking them, just to realize that they are not going to make it…

3. If you managed to set up an acceptable prototype site, start moving content, and script the transformations you need.

   Moving the content between systems requires a whole myriad of steps. One thing which will definitely give a headache is fixing shortcodes. I use 8-10 shortcodes, and a few of those are deeply tied to how the underlying system works. (E.g. my shortcode which I use for inserting images can use Hugo’s image resizing capabilities - now. But before Hugo, I had to do some really ugly Gulp magic.) So in this phase, I realized that it’s better to script all those find & replace operations. Oh, and I haven’t mentioned that the content structure is also different, new folder layout, new file names… so it’s super handy to have a script for this, because you will need to test this a gazillion of times to get it right. There are some even nastier possible issues, like when the new system interprets Markdown just a bit differently - I managed to ran into this, but at least I could configure Goldmark to accept most of what I had.

   This phase is successful when you have a shell script, you run it and in the output, you can’t really find any issues anymore. To reach this, I had to read all my posts numerous times, because I didn’t have any good idea on how to automate the checks, but still, somehow I got to the end. But if you’re super professional, you could think about setting up a sample file with all the custom tricks your content have - all shortcodes and everything - and solve that first, hoping that it will cover everything.

4. If you got here, you’re in the final stretch, only finishing touches remain, like being able to upload the content generated with the new engine.

   For me, this meant that I had to move the content with the new structure to the old Git repo. I also had to modify my GitHub actions. Fortunately enough, those actions - exactly because Hugo is easier to set up and better supported - became much easier, so it was mostly deletions.

This move provided quite a few learnings, especially about selecting the right components and systems. (Now, I believe this is going to be a solid solution for me. But it can easily happen that I will read this 4 years ago looking for advice to plan the next jump.) 🤣 One of the biggest learning is, I have to be always ready to write shell scripts, even if I don’t use it in my daily job. This level of usage doesn’t require a lot of bash-fu, but some tiny details can make things really awkward. My examples: realizing how it would be better to use GNU sed instead of the BSD one on macOS, and also, I had to look into how to utilize the find / xargs combo properly.

All in all, I’m now feeling good about this finally. I hope this feeling will stay. It would be nice if I could actually utilize this blog properly. I have quite a few writing ideas, so I “just” have to write. Anyhow, some positive feedback would be nice, so if you have anything to say, I would love to hear 😊