Returning from My Hiatus (hopefully 😅) & Introducing Hugo

It’s been a while (yes I said it many times). There is no denying that the activity on the blog has dwindled since 2019 (in fact, the last post with anything of essence was posted in Feb 16, 2019), and the 3 blog posts that follows are entirely “service updates” where I changed stuff around the blog.

This blog post is in fact not that much different - except I would like to pick up blogging again. A new article was just published (though it might be not to your taste 😝).

1 Another Theme Change?

Anyways, you might have noticed yet another cosmetic change to the blog. This time it’s no simple theme switch however - the entire blog is moved to the Hugo framework and served on Netlify.

Hugo is a static webpage generator, which is gaining traction in recent years. The main benefit of a static site is speed and ease of setup. I would like to detail some of the benefits of Hugo (vs. WordPress),
and my routine with the new setup.

2 Why Hugo

There are a number of great static site generators like Jekyll and Gatsby. I haven’t used the alternatives, but this comparison is more with regard to CMS like WordPress.

With static generators, you typically write your article in Markdown. Then, the generator “compiles” the Markdown files along with any images, stylesheets, scripts, and other items, and turn them into a website with only HTML, CSS, and JavaScript.

In my observation, Hugo is…

2.1 Much. Much Faster

Typical WordPress installations involves so called “LAMP stack”, or Linux, Apache, MySQL, and PHP. Articles are first pulled from a database, then combined with a theme/layout, executed by the PHP engine, before being presented by a web engine like Apache. On top of that, there can be dynamic loaded js like analytics, fonts, or even emojis that significantly slow down the final load time.

In comparison, static websites have way less moving parts - nothing needs to be pulled from database or dynamically rendered, as everything that’s needed for the website is already pre-compiled and ready to serve. As a result the website is much faster than a typical WordPress installation.

2.2 More Enjoyable to Work With

Writing in Markdown feels awesome with a coding-esque work environment, without having to figure out the nitty-gritty of HTML. This results in an improved productivity.

2.3 Transparent

This turns out to be a big deal to me because I really like having everything that builds the website on my filesystem and easily modified with VS Code (or other fine editors). Again, because the entirety of the site is just HTML (Markdown), CSS and JavaScript, I can add, delete, and modify however I like to my heart’s content with only a text editor.

Whereas on WordPress, I have to use the CMS to manage the blog and perform any changes, and often times I cannot find the file I need to edit that correspond to a part of the website, because WordPress is just the interplay of so many things.

2.4 Versatile

There’s a growing catalog of themes that drastically changes the look and the function of the website, for example my online CV is also powered by the Hugo framework, and it’s just as easy to update my publications entry on the CV than to add a new blog post on this site.

2.5 Able to Work Offline

This is just a nice side benefit of Markdown, but should I go offline during a trip or network outage, I can still work on my blog uninterrupted. In fact, most of the time I am writing offline, save for occasional online research for the article and the final GitHub upload when I finish (more on that later). I can get a rough idea what the article is going to look like before I even compile the page, and I can easily preview it locally by running hugo server. WordPress and the likes doesn’t work very well offline.

2.6 Multilingual

It’s no secret that I write in both Chinese and English (though in recent years I tended towards English). On my previous WordPress site both content were mixed together, and at times I even have to write both Chinese and English on the same page. I believe it is a huge distraction to the readers in both languages, as such I decided to offer the website in both Chinese and English. Hugo offers multilingual support out of the box, which makes it very easy to separate contents in different languages.

3 Why Not Hugo?

I also recognize that static generators like Hugo is not meant for everyone. Here are a few things I thought might be undesirable for some.

3.1 Steeper learning curve

It took me a while to figure out the basics of Hugo directory structure, and other important aspects like the front matter. Hugo has a Documentation online that, unfortunately, didn’t help me out very well when I first started. The docs is great as a reference, however. You are also assumed basic Markdown/HTML/CSS knowledge, and you will need to know a way to deploy your website.

As for WordPress you can either host your own instance, or use one of the many providers that saves the hassle of setup. WordPress also has a WYSIWYG-style (what you see is what you get) editor with a graphical interface, which might be preferred by some.

3.2 Not a lot of extensions

WordPress has a visibly larger selection of themes and plugins, that transitions WordPress to not just a blogging platform, but a online forum or even a shopping platform. What slows it down is what exactly made it powerful. Static site generators lack this extensibility because, by definition, you cannot have anything dynamic or even persist with just HTML/CSS/JS. So this is why many Hugo sites don’t support commenting - because it requires data to be stored.

But wait, doesn’t this blog have commenting? Yes, but it’s kinda cheating. The theme that I use supports Waline, which is basically an embedded js client that interacts from an edge function I deployed on Netlify, that in turn pulls data from a SQL database on PlanetScale. Which basically means that, yes you can have dynamic and persistent applications on Hugo, they just need to be outsourced.

3.3 Some HTML required

Markdown is ultimately offers only a subset of HTML features. It’s not surprising that, sometimes you have to use “hacks” for some things you take for granted in WordPress/HTML. For example, native Markdown does not support underline or image resizing, so I have to use some HTML workaround. Granted that the page turns into HTML anyways, but it kinda break the aesthetic of a pure Markdown page and force me to take detours to remind myself the proper usage of the HTML tags involved. And yes, there is no color support in Markdown, so be prepared to wrap your text around style="color..." block if you want it!

3.4 Difficulty of migration

If you come from CMS like WordPress, you have to migrate the entire site to Hugo. This is almost never a “loseless” progress, in the sense that you will lose out some content or functionality after the migration, plus you have to inspect and clean up every single post lest you want a half-functional website. My experience on that later.

4 My Routine on Hugo

Blogging on Hugo is as easy as 1-2-3:

1. I have my blog on a GitHub repository, and I work on a local clone of that repo. Every time when I finish working, I just commit the changes.
2. Once the changes are ready to go live, I push the commits to GitHub.
3. I set up a Netlify website so that it auto fetches the latest commit and builds the website for me. In mere minutes, the new content is online and available to the public.

There is certain magic with that modify-commit-publish approach, maybe it’s because I’m a programming oriented person. Who knows 😏.

There are many guides on how to set up Hugo with, say Netlify, including one from the official Hugo docs.

5 Migration to Hugo

One last thing on the whole Hugo transition. As I mentioned previously, the migration can be tedious and time-consuming. This is especially true for my blog.

There are a number of WordPress-to-Hugo plugins or utilities that aids the transition, however it turns out that simple export and import doesn’t work out great for the website.

For one, all the “regular” articles are placed inside the /content/post folder, with no hierarchy or organization. This means a huge headache just to categorize and place them in a neat, hierarchical order.

Second, (and more of my fault), I don’t have a consistent storage for the media in the blog. Some images from the early blog posts were stored locally, some images were stored in PhotoBucket, and one was stored on Amazon S3. Local pictures were transferred with the article, however they were also piled together in one folder. PhotoBucket pictures, on the other hand, requires payment to use externally without watermark and they were of lower quality. I decided to serve all the pictures locally and have them organized so they go into a folder where that picture is used. Another benefit of that approach is that my theme automatically scales the image to appropriate resolutions for optimized viewing, which is only possible if I serve the image locally.

Third, I also discovered a lot of junk code in the converted markdown, from my earlier liberal uses of shortcode and gallery plugins. I have to figure out what I was trying to do with the code involved, so that I can recreate them properly. A related issue is that some text formatting (bold, heading, etc) seems to be incorrectly transferred, so I have to manually inspect and correct them.

Still I found the process to be somewhat entertaining after all. I get to relieve myself on the great memories of the past, and remind myself how terrible I was at photographing 10 years ago!

To keep track of the migration process, I made a custom “Renovation” widget on the main page. Basically this indicate the number of articles I have reviewed and amended. Hopefully by the end of summer I can get them all processed.

During the transition, you will see Chinese articles listed in English website. This is normal and they will disappear (or rather, being filed into the Chinese site) as I work through them.

I will keep the old site open until then. You can visit it on old.kazumi.blog. Note that links might be broken because I didn’t go in and check all the links inside.