Moving to Hugo

This is part of the series: Publishing with Hugo

Have you ever had that feeling that perhaps (just perhaps) you were expending way too much time on something when you were almost certain there was a more efficient method? Did your familiarity or comfort with a tool cloud your judgement? Was your olfactory senses filled with pungent sunk cost fallacy?

Yes your honour, I plead guilty.

Link to this sectionWhere in the narrator flips the table

It all began about a month or so ago when I was wanting to fire up ye olde blog again, which was running on Drupal. Drupal, bless it’s massive heart, is a great system with much bell and whistle but when it comes to updating it can be a chore. This might consist of updating:

  • PHP itself
  • PHP libraries
  • Drupal core
  • Drupal plugins
  • DB conflicts (rare)
  • Templates
  • Infrastructure tooling

And that’s just locally on my machine. Depending on what updates were made, the hosting too might need updating. Best case, which is just running composer update, could be looking at a few minutes. Worst case, a day or so and given my setup and how far behind everything was, it was going to be the latter.

(╯°□°)╯︵ ┻━┻

So given that, I started to look around. It had been a while since I had peered over the blogging platform fence and specifically the dynamic vs static site generator divider and last time I hadn’t been that impressed. But it had been a quite while (years) since I had looked and what I found now looked… good – very good.

Link to this sectionThe static site party

For those out of the loop, a dynamic site is one that generates everything on demand – it pulls the content probably out of a database, runs it through a bunch of code transforming it on the way and then shoves it into one or more templates for display. This happens every single time a visitor wants to view a page. Sure, you can put a cache in there, but the number of layers in the stack is the same. The most popular dynamic platforms such as Wordpress, Joomla and Drupal all run on PHP and with a database and can become very complex as they support all sorts of plugins that add extra functionality – and yes, that often opens up more attack vectors to be hacked aswell as more things to be maintained (as mentioned above).

At the end of the day, the output from these platforms is still only HTML pages, styled with CSS with a smattering (at least, sometimes more) of Javascript. This is where static site generators (SSG) come in. Their philosophy is to not generate pages on the fly and instead focus on tooling that pre-generates HTML, CSS and JS. Content is often stored in a very simple text format (e.g. Markdown) which is transformed using a templating system. This all happens once to generate the whole site.

In my case, what I needed included:

  • categorisation using tags and series
  • syntax highlighting of code snippets
  • listings of pages and tags, pages that are in series
  • publishing on a certain date
  • posts and normal page content types

Sure I couldn’t log in to my site to do remote updates or just turn on a commenting system or even enable site search but neither did I really care about or need those things and there are SSG ways to do some of those that are “good enough”.

Last but not least, a website that is only bare HTML and CSS is fast. Optimisation is more or less a matter of paring down file sizes.

Given all that, an SSG ticked a lot of boxes - if you want to know more I suggest reading about the Jamstack .

Link to this sectionPicking an SSG

When I started evaluating SSGs, I saw a couple of main types.

Link to this sectionClient side rendering with fallback

This type of SSG is usually based on a Javascript framework such as Vue or React. This can give added benefits such as very fast page loads (after the first page), and application like animation and functionality. Examples of this kind include Gatsby, Nuxt and VuePress.

Link to this sectionServer side files only

Even more simpler is are SSGs that only create HTML, CSS and very minimal Javascript (if any). Examples of this kind include Jekyll, Hugo and Zola.

Technically I had no issue with either approach, however, in the end I felt like the less things to worry about the better. Having to maintain an additional Javascript framework seemed unnecessary given what I cared about and the benefits seemed incremental at best.

In the end I ultimately went with Hugo primarily because:

  • maturity and well maintained
  • it’s just a single binary
  • very fast to rebuild the whole site – mere milliseconds
  • great markdown with frontmatter support
  • extensive documentation
  • Go templating is well structured, powerful

Link to this sectionThe great conversion

From a high-level, once I made the decision to go with Hugo I did the following:

  • clean up all existing content, export some missing items into markdown files
  • make a new Hugo theme, roughly:
    • start with a base template, get something showing
    • scss setup and generating into css
    • break the base template into post and single page templates
    • create partial template for menus, headers and footers
    • style everything out to match my previous Drupal theme including syntax highlighting
    • mess around adding new features cos, you know, shiny things!
  • figure out how to get it all on the web
  • clean up and tweak everything

Link to this sectionObservations

Overall I found the whole experience to be a blast. Here are my impressions/feels so far:

  • Hugo requires a reasonable level of technical competency. You can probably get away with installing it and an off-the-github-shelf theme and start writing your posts in Markdown. However, if you want to do anything more than that you are going to have to learn some Go templating. Again, relatively straight forward if you are familiar with such things.
  • Hugo has a built-in web server for local preview with live reload – I love it. You can have your text editor open in half the screen, your web browser on your local site on the other, hit save and see the changes right away.
  • Did I mention that Hugo rebuilds the whole site in milliseconds – I’ll mention it again!
  • Although the documentation is relatively complete, it can sometimes be hard to find exactly how something is done – I think an index of recipes and more how-tos beyond the Getting Started section would sort that out. Following on from that, some kind of “best practices” section would be fantastic.
  • Hugo is a command line tool, again might be a non-starter for many

In the next post I’ll go through some tips and tricks and how to do certain things in Hugo that weren’t obvious to me at first glance.

  • //Series: Publishing with Hugo
  • //Tags:
  • //Posted: April 17, 2022
  • //Updated: April 21, 2022