Brandon Risberg

Hugo

Hugo is a Static-Site-Generator written in Go. It claims to be the fastest SSG around because it is based on Golang’s html/templating libraries.

It can be used to generate beautiful static websites and comes with a number of themes to choose from.

Installation

I chose the simplest installation for macOS, using Homebrew.

brew install hugo

Pin the version somewhere the build reads too, so your machine and CI cannot drift apart. This site keeps it in a .hugoversion file at the repo root.

Installing themes

Themes can be vendored as Git submodules or pulled in as Hugo Modules, which is the modern approach and no longer experimental.

I use neither — this site has no theme, and its layouts live in site/layouts/. Three abandoned theme submodules and a config still describing a theme I had already swapped out was what finally convinced me that for a site this small, owning ~150 lines of HTML is cheaper than maintaining someone else’s abstraction.

Customizing

You can customize nearly anything you like about Hugo (and then export that as a theme if you wish). Or you can layer your changes on top of an existing theme.

Hugo makes a bunch of assumptions about the structure of your site, as all of your content pages will be under the content/ directory. Depending on which subdirectory you choose it will interpret the content type. You can override this with a Front Matter, basically a YAML block at the top of the markdown file which Hugo will use when generating. The Front Matter can override most things.

It is useful to examine the theme for which layouts / config params it is looking for. There isn’t a clean declaration of all the options available. See variables docs for existing builtin Hugo variables at the Site and Page level.

Some useful ones: