The Hugo Experience

Introduction to the problem

I’ve been working on this website continuously for the past 2 weeks getting it to a stage where I can write thoughts and it appears on the page. This has been tricky in the past since I only used pure html. Every time I wanted to create a new page, I would need to copy over the template file and add my musings in raw html, which got pretty frustrating when the layout gets messed up because I forgot to close a <p> tag.

Sometime around when I moved, I found a Codeacademy course on setting up Jekyll with Github Pages. It was very well made and they even gave you your own shell to type the commands on, and you would get a real working website on your github account once you were finished. At least that was what was supposed to happen, I think I got an error towards the end despite me typing everything exactly and passing the other lessons. I thought nothing of it and abandoned the effort, though I continued to use Github Pages to host other websites I made. This year I decided to make a website archiving all my other websites. I realised that crating a nice looking page would not be possible with my rusty html and css knowledge, which made me think about jekyll again.

About Jekyll

Jekyll is a static site generator, meaning instead of creating dynamic webpages that use a backend such as php or node.js, it outputs pure html files. This has the advantage of being more flexable as many free hostng platforms will only accept html files. It also allows pages to be created in markdown, which is vastly easier to write pages with than html as it is mostly plain text with markers for things like headers. Finally, there are plenty of premade themes to customise the website, thought I stuck with the default theme, minima. I started my archive site using the github pages tutorial on jekyll as well as the jekyll quickstart guide. Once it was fully set up, it was much easier than managing my own site. Themes could be included simply by adding the name to _config.yml and jekyll-remote-theme would included it straight from the github repo. Also, themes were really easy to override as includes and templates each has their own directories and layouts are defined explicitly for each markdown page.

However, Ruby, the language jekyll is made in, was the main issue I had. Starting out I had trouble configuring bundle and realised I needed to set my gems location every time i needed to use it. Also, some dependencies I needed such as json weren’t in the Gemfile and not mentioned in both guides. Also, when I want to work on the website on another computer, I first need to install ruby and then go through the whole bundle business again, which seemed too much for a website to me. Basically everything is a gem too including local themes. It wasn’t just me either, the people running blahaj.land also had issues configuring jekyll for autobuild and suggested I try other SSGs such as Eleventy, Hugo, and Zola.

Enter Hugo

I ended up trying hugo, which is written in Go, for this blog and from the start it fixes the number one issue of dependency hell. Like, its just one executable that you can get with most package mangers. Also, everything is included, so no more gem bundles. Also, it finishes generating much faster than jekyll being basically instant if you have an ok processor (rip raspberry pi taking 3 seconds lol). Also, there’s no dedicated posts folder, all non-section pages are treated the same, so no messing with specific filename structures to show the page is a post.

Themes work a little differently in that the theme is included in the website project itself, which makes things interesting when you want your theme on a seperate git repo than your website. Initially I used submodules to include the theme, but that had issues when I either forgot to initialise the module or update it to the latest commit. Also, the deployment scripts for blahaj.land weren’t made for submodules, so hugo would be confused as to where the theme was. After just including the theme in the same repo as the site, I eventually stumbled on subtrees , which still include the theme in the same repo but allow it to be synced with an external repo. As a bonus, changes made in the site can be synced back to the external repo.

Asides from that, page layouts are inferred rather than explicit. There are some indicators you can change such as underscores indicating section pages (like the posts listing), but other than that, you just have to make sure your templates are specific enough that hugo will match it to the page you want.

Conclusion

Hugo overall is a very solid SSG, and I can live with the quirks. Like i did with jekyll, I’ll stick with it until a major issue prevents me from continuing further. Zola does seem like a good alternative being written rust so keeping all the advantages of hugo, as well as using about the same format for configuring pages and the site itself. For now though, the benefits aren’t worth it, especially now that my blog is configured pretty much the way I want it.