I’ve worked with several sites built by Jekyll (written in Ruby), particularly on GitHub Pages, but for this site, I’ve decided to give the Hugo (written in Go) a try.

Why specifically Hugo? Given the Go implementation, I looked forward to not having to deal with Ruby versions & environments, and Ruby gem dependency incompatibilities. Having worked a bit with Go, I was looking forward to a much simpler experience. I also liked several of the themes written for Hugo, and wanted to try some of them out.

So how did it work out for me?

Well, this very blog that you’re reading (at least, at the time of this writing) is generated by Hugo! And no, I did not have to worry about building any Go source code, or deal with any dependencies or libraries to get it to work.

I will show you the steps I went through, so that you might have an easier time, if you decide to take this route as well.

Installing Hugo

To start building a site with Hugo, we need to first install Hugo. This is pretty straight-forward; given that I was using Ubuntu, I ended up simply running:

$ sudo apt install hugo

which provided the /usr/bin/hugo binary, so we can get started.

Choosing a theme

Now we need a theme for our site. Because I was starting from scratch, and didn’t yet have any content to post for the blog, I wanted something akin to a splash page to start, so I wouldn’t have a blank page for users visiting my site.

Thus, after looking through a number of Hugo themes, I ended up with the minimalist theme Hermit. I liked the simplicity of the landing page, and the combination of grey background colors.

Many folks suggest just forking a theme’s source repo and modifying the content inline, but given that the changes will be quite invasive, this approach makes it really hard to:

  • update the theme to incorporate the latest changes from the author, and
  • switch the site from one theme to another

so I recommend a different approach that I’ve seen elsewhere: using Git submodules. This allows us to keep the theme repo versioned separately, and have our content and configuration versioned separately. Upgrading the theme is as simple as updating the theme’s submodule, and moving to a different theme is as easy as adding the new theme as a new submodule, updating the config, and removing the old theme.

Note: this post assumes you’re familiar with both Git and Git submodules.

Building & testing your site

Here’s what I did:

  1. Create a new git repo:

    $ mkdir my-site
$ cd my-site
$ git init

  2. Add the theme as a submodule:

    $ mkdir themes
$ git submodule add https://github.com/Track3/hermit.git themes/hermit

  3. Add Hugo configuration customized for the theme you chose

    Hugo themes typically have a directory exampleSite in their repo which is used to demonstrate the look and features of the theme. Thus, you can look in Hermit’s exampleSite folder to find a file named config.toml which you can use as a starting point:

    $ cp themes/hermit/exampleSite/config.toml config.toml

  4. Preview the site locally by running the Hugo server to generate the site:

    $ hugo server --disableFastRender --verbose

    and opening the URL provided in your browser to see the live-updating site preview.

  5. Modify the config.toml file to suit your needs, e.g., by adding links to your social profiles. You can add an about page via:

    $ hugo new about.md

    Be sure to update the config.toml to add a link to the new page you’ve just added.

You should now have a working site that you can preview in your browser, so let’s deploy it!

Publishing your site

GitHub Pages supports automatically publishing pages via Jekyll, but what about a different static site generator, such as Hugo? You can certainly get this to work using a combination of GitHub + build service, such as Travis CI, but that is some additional work, involving creating deployment keys, encrypting them, etc.

Luckily, GitLab provides both a source code hosting site, as well as building and publishing sites via many popular static site generators, including Hugo!

All you need to do is to add a .gitlab-ci.yml file to your repo with the steps, and they even have sample files that can be used as-is. For example, for Hugo, there’s the GitLab Pages example repo for Hugo which includes a sample config you can start with:

# All available Hugo versions are listed here:
# https://gitlab.com/pages/hugo/container_registry
image: registry.gitlab.com/pages/hugo:latest
variables:
  GIT_SUBMODULE_STRATEGY: recursive
test:
  script:
  - hugo
  except:
  - master
pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - master

You can use this file as-is in your own repo, and it will publish an updated version of the site on every commit.

This is how I deployed the very first version of this site.