I customized a static site generator written in shell script 5 years ago: Minimal Blogging Setup with Orgmode and ssg5. Last year, I reinstalled my operating system. On Monday this week, I tried to build this website and the website would not build. After a whole night of debugging my script, I gave up and decided to migrate to Hugo. Here is what I learned while migrating the site.

I did not want to lose my old posts and I did not have to! It was nice to keep my memories of 3D printing ear savers for nurses during the pandemic.

Why did I write my own?#

Back in 2020, I wanted to get better at shell scripting and I wrote a static site generator in shell script to learn. Over the years, I added dependencies on programs like openring and bash, and random small scripts on my system. Although this was a great learning experience, I rely on this site to publish my ideas and it needs to be easy to update. I needed the RSS feed generator (written in shell script) to work but it would often break cause of some input the generator didn’t expect. Last Monday’s problems caused me to adopt the popular boring option (Hugo).

Why Hugo#

Speed#

Hugo is very fast at generating HTML. This speed allowed me to quickly iterate over designs and changes. When transitioning my website, I noticed I could just run a local server with: hugo server --buildDrafts --navigateToChanged. This command will quickly build all posts even ones marked as “draft”. I was able to jump around in Emacs and save the file. Hugo would automatically navigate to the new version of the page I just changed or refresh my web browser so I can see the changes in action. This is feedback loop is much faster than my old setup - I had to manually navigate to the changed page and refresh the page.

The speed of setting up a new development environment also appealed to me. Hugo is a single statically-linked binary and I’m able to immediately work on a blog post on any new machine without mucking around with my package manager.

Popularity#

The popularity of Hugo makes it more likely that any problem I run into will have a fix online ¹. Debugging a static site generator when a post needs to go up or changed is annoying. Finally, since Hugo is so popular, there is Hugo integration for everything I use - sourcehut had documentation on how to host a site using hugo.

Themes#

With Hugo, the content and theme are decoupled. I like changing the theme of my website and this allows me to avoid breaking content when I just want to change the theme.

Problems#

Overall, the transition from my static site generator to Hugo only took two hours. The migration issue was the new defaults which I actually liked and made me more convinced that this was time well spent. Here are some of the changes I needed to preserve backwards compatibility.

Broken links#

In Hugo, by default, all URLs are lower case and do not have the path extension ². I like the URLs hugo generates because they are easier to type in. However, the internet already contains links to my blog using the old ugly links ³.

I can disable “pretty URLs” to bring back the path extension and disable lower casing in the settings of hugo: hugo.toml. But, URLs with mixed case characters AND path extensions still didn’t work. Moreover, I wanted all future posts to use the new pretty URL generator. Luckily, I made a workaround using Hugo aliases ⁴.

For example in my ssg blog post (written in Orgmode), I added the following alias:

#+aliases[]: 2020-07-21-ssg.html

Now, you can go to https://momi.ca/posts/2020-07-21-ssg.html (old, ugly URL) or https://momi.ca/posts/2020-07-21-ssg (new, pretty URL) to access that blog post.

Similarly, for my post about Corona virus ear savers (written in markdown), I added the following front matter:

aliases: ["2020-04-05-3DPrintingCorona.html"]

Now you can go to https://momi.ca/posts/2020-04-05-3DPrintingCorona.html (old, mixed case and ugly URL) or https://momi.ca/posts/2020-04-05-3dprintingcorona (new, lower cased and pretty URL).

I was able to add aliases to all my blog posts within half an hour using Emacs macros.

Aliases are another reason to switch to Hugo. With my old static site generator, I had to keep URLs that I misspelled because changing the filename would break links. With Hugo, I can move files around to generate the best URLs and just add aliases as needed.

RSS#

My old website served the RSS feed at https://momi.ca/feed.xml. I had to add the following option in my hugo.toml to make sure subscriber’s RSS readers kept working:

[outputFormats]
[outputFormats.RSS]
mediatype = "application/rss+xml"
baseName = "feed"

Sourcehut CI#

I chose sourcehut CI and sourcehut pages to host my website. I want sourcehut CI to build my website so I’m never in a situation where I cannot update my website. I was able to set this up using the hugo documentation.

Conclusion#

This site started out as a fun project but overtime, it has grown to host a lot of important documentation for myself. As such, it holds a lot of value in my life and I’m happy I was able to simplify the entire website. I can now update and change the content with one git commit. I don’t have to worry about a malformed RSS feed. Moreover, if I get bored of the theme (which seems to happen every couple months), I can change it without fear of breaking core functionality.

Did I break something? Feel free to send me an email: anjan -at- momi.ca