Hugo First Impressions


My last website was set up using Middleman as I’ve been building lots of things with ruby so it felt pretty natural. However, I was using a completely handcrafted theme and I’m really not that much into creating layouts and figuring out all the quirks of mobile and non-mobile CSS across a variety of browsers.

CSS madness

How I feel about styling an entire web site

So getting new things out there started to feel a pain and I had at least two rewrite operations of asset pipeline/typography/etc going on at any given time.

I finally noticed that I had been working six months at a new job and my website still told I’m working at the Previous Company. Something needed to be done. I had been looking at Hugo for a while but never tried it out as I hadn’t ever felt the need to speed up the technical part of site rendering, and speed is one of the core offerings of Hugo. However, I decided to give it a try.

Introducing Hugo

Hugo is a static site generator built with Go. It promises blazing fast speed and lots of flexibility. At its core are themes, which tell it how the site is rendered, content in the form of markdown documents with frontmatter support, and a bunch of other things like image processing and shortcodes for markdown.

First steps

I decided to skip most of the pain points I had with the previous site and just go with an existing theme. After taking a look at the very nicely productized themes catalog I decided to go with the simple Goa theme, as it provided a very simple blog theme and a lightweight frontpage.

It took me some hours to get acquainted with how Hugo works, port my existing content (which is very little) to the new platform and get cracking. And I have to say holy shit this thing is fast. Currently, the total time it takes to both build and deploy the site is exactly a second. As I’ve been previously running a static site on my own server, it was a breeze to just change the rsync command to copy the new contents to the site root.

I’ve now spent another couple of hours tweaking the setup and getting more intimate with all the knobs out there. I’m also writing the second post. Contrast this with my previous website project which usually took me an entire evening to just get into the “I’ve now broken everything and want to just start over” part without ever getting to the content part.

Hard parts

Figuring out where to put things felt a bit difficult. There’s a ton of documentation at the website, but some small things weren’t very intuitive, or at least took me a couple of tries to get right. I moved the couple of images that the site has around for a while to get them to replace the ones the layout provides, get them processed by the image pipeline and get the URLs sensible in the post content, and all of this to be happening at the same time. I think I still need to get a better sense of how the overrides and image processing works.

I was also struggling for a while to realize that unlike in Middleman, you just can’t run template code everywhere. The markdown files just print it out verbatim and again figuring out what needs to be done to get the results I want took some time.

Good parts

The content vs. layout thing is actually something I like a lot. It sets pretty clear separation of concerns and doesn’t let unnecessary things leak into the content. There’s also a surprisingly big amount of customization that can be done just with the markdown files and front matter without ever touching the layouts.

Did I mention this thing is fast as hell?

Also, starting from a theme was clearly the right thing to do in my case.


Some things I still need to tweak and figure out:

  • Code highlight. It seems to be possible both through highlight.js as well as a prerendered markdown renderer. I kind of want to keep the frontend as light as possible, so I’d prefer the prerendered case but let’s see how that setup goes.
  • I’m not that fond of web fonts as they always mean more time to render the initial page or sudden reflows. I’ll need to figure out how to tweak the theme so that it’s still maintainable.
  • The theme has some features where the contrast is just not good enough. Some of the footer texts are not very visible as well as links versus regular text differentiation is not enough.
  • Seems like images need a touch of CSS.
  • The menus and other cross-links are not visible in enough places. Need to figure out how they work.