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 😝).
This blog is now offered in English and Chinese.
You can also use the language switcher on the lower-left corner of the page, or use the link at the top of the page to view the page in a different language (where available).
Both sites are different in content. It is unlikely that I have time to to retroactively translate some 100 articles into a different language. As a general rule, more recent articles are written in English and older articles are in Chinese. If you found some articles missing, they are likely offered only in a different language.
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.
In my observation, Hugo is…
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.
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.
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.
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.
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
WordPress and the likes doesn’t work very well offline.
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.
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.
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.
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.
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 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!
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.
Blogging on Hugo is as easy as 1-2-3:
- 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.
- Once the changes are ready to go live, I push the commits to GitHub.
- 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.
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
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.
If you find this post helpful, please consider buying me a coffee :)