Getting started with Hugo static site generator

Static site generators

A static site generator is an application that takes your content as input and turns it into a static website (which means: HTML pages linked together with some CSS styling).

Static websites have the advantage of not requiring server-side processing to generate HTML pages dynamically. They’re typically faster to load, can be hosted on virtually any web server, and can be cached easily.

Among many use-cases, a personal blog is a great one. The fact that it’s typically single user makes a CMS less relevant.

Getting started with Hugo

These instructions will show you how to configure a hugo static website development environment on your workstation:

  1. Download and install hugo.

    I found it worth it to get the latest release as my apt repository was way behind on available versions.

  2. Execute this command to create a new project structure in a directory.

    hugo new site SITE_NAME

    The most important subdirectories are content/ where your pages content will be, and themes/ where you’ll need to add a theme that will render your website in templates.

  3. You need a theme to display a hugo site. The command to create a new site doesn’t give you a theme by default. You can look at themes from the community here and download one you like. You must then put it in its own directory under themes/ of your project.

  4. Add a line in config.toml to refer to your theme by its name:

    theme = "blank"

  5. Execute this command to dynamically build the static site and serve it locally on port 1313 (by default).

    hugo server --buildDrafts

  6. Execute this command to create a new post:

    hugo new posts/my_test_post.md

    You’ll see a new file appear under contents/posts/. You can add content under its header in markdown format.

  7. Browse:

    http://127.0.0.1:1313

When you use the hugo serve command, there’s Javascript appended to each generated page that will trigger automatic refresh of the page when you edit files in your project directory.

Deploying the website

Running the hugo command without any parameter builds a public/ directory with the static files ready to be hosted somewhere. All you need to do is upload the content of public/ to your server.

This website project is version controlled on git and hosted on GitHub. CircleCI is configured to deploy the website on AWS S3 (object storage), which is in turn served by AWS Cloudfront (CDN). These other posts explain how to deploy the required infrastructure with Terraform and configure the build system: