Hugo

This site has been through many iterations over the years. These have ranged from a CMS I built myself just for fun and for my friends and I to use, to shudder a Wordpress site. Most recently, I’ve been using Hugo for content management.

Things have been fine.

I very much like the idea of something where I can just type some works into a Markdown doc and not have to worry about styling (mostly). I’m a backend and infrastructure guy - I just don’t care enough to dig into doing all of that anymore. But I do want things to look non-terrible, so I needed to do something.

I won’t go into the ‘what’ of Hugo, but will rather take this opportunity to mention what I’ve liked about it, and what I’ve very much disliked. I’ll also touch on my deployment and hosting a bit.

Good Stuff

Getting started is pretty easy. You just install Hugo, pick a directory, and init into it. This will give you a basic project structure that you can immediately start playing with.

Configuration is mostly handled in a single file, which can be any number of formats (I’m using YAML just because that’s what I spend 63-94% of my day editing anyway). This makes finding and changing what you want simple enough, though there are caveats (see below).

Content authoring is also solid. Multiple formats are supported, so you can do things in pure HTML if you like, or a dialect of markdown.

Iterative development and testing is also pretty easy with a simple HTTP server built in so you can review your work on localhost as you go.

There are also scores of themes to pick from, and ‘installing’ a theme is as simple as adding it as a submodule or just unpacking it into a themes directory. Most of the themes are decent looking, and all can be modified to some degree to fit whatever specific needs you may have.

Bad Stuff

Most of the ugly stuff is just flip sides to items from above.

Configuration is confusing and can vary wildly depending on the theme.

How your content is handled can change based on the theme to some degree, often without any obvious rhyme or reason.

The themes don’t all support the same ‘shortcodes’ and features, so it isn’t always easy to switch between them.

My biggest problem with Hugo, and this extends to almost every theme I’ve looked at, is the documentation is quite poor from the perspective of someone that just wants to use it. The docs are great if you’re elbow deep in the project and making your own themes and customizing how stuff works under the hood. But if all you want to do is yell into the abyss that is the internet, then it isn’t always easy to figure out how to do things like include media in a post or have your pages sorted in a certain way, or remove that one weird thing a theme may do that you hate in something otherwise wonderful.

I suppose that’s the curse of pretty much any project like this, though. I’m not sure I’d recommend Hugo to someone that isn’t already familiar with most of the core concepts of a site, though. In that way, it isn’t on par with any of the more intuitive publishing suites available.

How I’m using it

I’m hosting this on S3 behind a CloudFront distribution. The infrastructure is built with the AWS CDK in a quick and dirty application I wrong to standup static sites and all the parts needed to make them work the way I want.

The site content is stored in a git repo, and whenever I want to publish I just something like this:

hugo -D &&
aws s3 sync --delete ${LOCAL_PUBLIC_DIR} s3://${TARGET_BUCKET}

And then I just kinda wait for CloudFront to expire the cached stuff. Simple, safe, secure, and super cheap.