Using Hugo for a simple web site and porting the Drupal Zen theme

Hugo logo.

A couple of years ago static web site generators was the next big thing. I have been meaning to try one out and last week I had the opportunity.

I went to Top Open-Source Static Site Generators - StaticGen to see what the options where nowadays. After testing a few, mainly Python based, I picked Hugo :: A fast and modern static website engine written in Go.

Things that appealed to me initially was:

  • No dependencies and the built in features suited me well.
  • Really fast.
  • Good documentation.
  • Easy to install on macOS.
brew install hugo

And you are done (get Homebrew).

I started by creating some content. You do this by creating Markdown files in the content directory, manually or with the “hugo new” command. At a minimum they need the “title” metadata and “hugo new” will always add “date” as well.

---
date: "2017-03-12T08:58:37+01:00"
title: "The title"

---

The text is added here below the metadata. The metadata can be in different formats, I opted for yaml.

With some content in place the site can be generated by the “hugo” command. The result is added to the “public” directory. It’s the content of this directory that is your new site and that you deploy to your server.

A new section/content-type is created by simply adding a sub folder inside “content”. Each section can have it’s own templates and archetypes.

To control the look of the site you need a theme. At Hugo Themes Site you can browse a selection of them. I’m used to work with the Drupal zen base theme so decided to port that to Hugo, frjo/hugo-theme-zen.

This way I can write sass with the same structure as I do in Drupal and generate css quickly with libsass via gulp.js. With the help of gulp.js I added minifiction of the css and plan to also add generation of scaled images. The original zen theme does not do this since Drupal has it built in.

What meta data is added to a new post (when using the “hugo new” command) is controlled by archetypes. Your theme can have them and you can easily override them by placing new ones in the sites “archetype” directory.

Hugo consistently looks for templates and such first in the site directories, then the theme and last fallback on Hugo defaults. On each level it will first look for section specific alternatives that are placed in a directory with the same name as the section and then fallback on the “_default”.

The only thing I struggled a little bit with was creating a custom front page. By default the “list.html” template will be used to list all the content of the site. This is maybe good for a blog but not in most other cases.

By creating a “index.html” template inside “layouts” directory and a “_index.md” file in the root of the “content” directory you get a custom front page. The content of the “_index.md” file gets inserted in the “index.html” template with the “{{ .Content }}” tag.

In my simple case pages are built up like this:

baseof.html <- index.html <- _index.md

baseof.html <- list.html <- [list of content]

baseof.html <- single.html <- some_content.md

With the site done I wanted an easy way to deploy it to my server. Since the site is a simple collection of static files this was all that was needed.

A one line deploy script:

#!/usr/bin/env sh

hugo && rsync -e 'ssh -ax -p 22' -avz --delete --exclude '.DS_Store' public/ host.example.com:/var/www/

I can certainly see the appeal of static site generators. It’s a structured and efficient way to create and maintain content. And the end result can be hosted almost anywhere, is fast and secure and don’t need any maintenance or updates, deploy and forget if you want to.

The result is this small site about Helmer Grundström. I am looking forward to using Hugo again.