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.
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.
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:
Create a new git repo:
$ mkdir my-site $ cd my-site $ git init
Add the theme as a submodule:
$ mkdir themes $ git submodule add https://github.com/Track3/hermit.git themes/hermit
Add Hugo configuration customized for the theme you chose
Hugo themes typically have a directory
exampleSitein their repo which is used to demonstrate the look and features of the theme. Thus, you can look in Hermit’s
exampleSitefolder to find a file named
config.tomlwhich you can use as a starting point:
$ cp themes/hermit/exampleSite/config.toml config.toml
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.
config.tomlfile 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.tomlto 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.