Hugo: First impressions

Blogging is hard. Not just forcing yourself to write, but setting up a blog in the first place. Sure, you can go with a plain old Wordpress install, but as a tech geek, that isn't going to happen. I looked into static site generators a while ago, but never got past the "looking into" phase. Then I stumbled upon Hugo.

Hugo is written in Go (which makes it really fast and portable!), but what caught my eye was the vast amount of documentation available. It turns out it's quite flexible and easy to extend. Creating a custom theme, setting up custom content types (archetypes), and creating custom short codes is a breeze.

In just a few hours, I had a working website. The process of building my own site (and theme from the ground up), was really smooth. Hugo has live reload built in (run it with the -w / watch flag), and will immediately update in the browser when you change either your CSS, template files or content.

I'll try to give a brief overview of what a Hugo site consists of.

Templates and theming

Hugo uses the Go html/template language from Go's standard library. It's a lot more limited than for example Django or Jinja2, both of which I've used extensively, but I found that the additional functions Hugo provides, made it quite nice to work with. If you prefer an indentation based syntax for your HTML, it also has support for the Ace and Amber templating languages.

CSS and static files go inside a static directory in the root of your site. Alternatively, you can create a full, reusable theme with its own assets and template files inside themes. Then switching to another theme becomes as simple as adding theme = "mytheme" to your configuration file. There are also some themes available on Github.

Content

All you need to do to create a new blog post / page with Hugo is to call hugo new path/to/page.md, and a new page is created inside content/path/to/page.md.

It'll look something like this:

+++
date = "2015-07-21T21:23:21+02:00"
draft = true
title = ""
+++

Hugo supports three configuration formats: TOML, YAML and JSON. TOML configuration is wrapped in +++, and YAML is wrapped in in ---.

After the configuration block, you add your content. This is written in Markdown. You can augment it by using short codes and even inline HTML, if you need to.

If you want to add additional configuration variables to your content, you can create your own "archetypes". These are basically content templates. If you have an archetype called post.md, and call hugo new post/my-post.md, Hugo will use the post.md template to create the new blog post.

Configuration

As I said above, Hugo supports three configuration formats. In addition to the per-content configuration, you also need a site config file. This lies in the root of your site, called either config.toml, config.yaml or config.json.

It may look something like this:

baseurl = "http://olav.it/"
languageCode = "en-us"
title = "olav.it"
author = "Olav Lindekleiv"
paginate = 5

[taxonomies]
    tag = "tags"

There are lots of configuration variables to play with. A full list can be found here.

Conclusion

There is a lot more to Hugo than what I've covered here. Go read the documentation if you want to dig into the details. This post is more of a bird's view introduction to give you an overview of what you need to know to get started.

Hugo has been able to do all that I've wanted from it so far, but I'm sure I have more to learn. Now I just need to fill this site with some useful content!