Building the site with the Hugo static site generator

Posted on Jan 12, 2023

Motivation

It is not the first time I make a web site and I still fondly remember the time when we could just drop a bunch of HTML files in a given folder on our institute web site and we could have our own pages (it was pretty wild). Next, and mostly to share my growing knowledge on photography, I used the wordpress giant (aboutfoto.wordpress.com) for a personal web site.

While initially the web site was mostly to talk about photography, it ended up by being used to share information about data analysis and visualization, with R and Python. When a GitLab instance became available for the institute, I migrated those pieces of advice to a more appropriate site: gitlab.pasteur.fr/csaveanu. In parallel, I had the ambition to maintain a web site, but I was concerned about making it as I liked. Static web site generators, and Pelican, a Python-based one, were nice. However, the whole process of setting up the site on GitLab pages seemed overkill for the result.

The next step in the journey to a Hugo-powered site was the complete shift of the research site of the Pasteur Institute to a WordPress solution. That was nice, as we could have our own pages with links to PubMed, GitLab and other resources and the whole editing process is quite easy. Still, the imposed layout and limited, by design, posibilities, were somehow frustrating. I had the opportunity to microblog on Twitter, but, progressively, that site became more and more aggressive, even if interesting information was still to be found.

Enter 2022 - Twitter was bought by a person who considered moderation to be relatively unimportant and made changes to the site that seemed to further enhance its negative sides. So I switched to a Mastodon instance on which I already had an account and which became my main presence on the social networks. A lot of talk on Mastodon turned around “owning” our own data on the web, and I decided that it was time to try to set up a, hopefully, long term web site that would be only dependent on having a domain name and service provider.

Owning a basic web site

It did not take long for me to choose a domain name and paid for the hosting solution that I could find. It was quite painful to understand how the redirections work and especially how the certificates required for a HTTPS site can be generated and associated with the site. In the end, thanks to many people having the same problems and to the available guides, the static site works and serves pages correctly. Since the content is generally light, I expect the small site to load fast and be usable.

The very first web site consisted of a simple index.html page with the following content:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="css/pico.min.css">
    <title>Hello, world!</title>
  </head>
  <body>
    <main class="container">
      <h1>Under construction, sorry</h1>
    </main>
  </body>
</html>

If you are familiar with HTML, you can see that a css/pico.min.css asset is called. This one comes from the minimalist Pico.CSS library that served to make the appearance of this first page less “rough”:

Under construction page

There is an appeal to create a small site from very basic HTML pages with a minimal CSS library. Still, it was interesting to use the collective intelligence of the Internet to help me build a site that would be relatively easy to maintain, especially when adding new pages or posts. Hugo was the obvious choice, although I must confess it took some time to understand how the templating system works.

Finding the right theme and technical issues

Strangely, Hugo does not come with a pre-installed theme and does not work at all without one. Currently, a collection of a few hundred themes give a lot (too much) of choice. Having failed to build rapidly a Hugo theme from scratch, I settled on Archie by Athul Cyriac Ajay, since the theme structure was relatively easy to understand and customize. I thank the theme author for his work on this light and nice theme.

My advice for people starting with Hugo is to use the simplest possible theme because it is less likely to break over time and it might also help with the speed of page loading and display. I use both HTML and MarkDown for the posts and pages sources. HTML is great because it is something many people are familiar with. Markdown is less verbose and might help with gaining some speed when writing posts. However, more complex and page-specific layouts are pretty impossible to do with Markdown. This is why, for example, the Publications page of this site is written in HTML, because it allows, by including the right css files, some useful effects (zoom of images, image and text side by side).

There is a way to trick Hugo in using HTML code written in an md source. It involves the addition in the layouts/shortcodes folder of the site of a rawhtml.html file with the content: {{.Inner}}. In pages where raw HTML is needed, one can use these “custom” open {{< rawhtml >}} and close {{</ rawhtml >}} tags. However, it might be easier to write the page in HTML, with the appropriate yaml or toml heading.

Comments are also a thing that I find important when writing. Multi-line comments are possible in the current version of markdown supported by Hugo. They can be written like HTML comments using ‘<!–’ and ‘–>’ tagging.

Also, while I was attracted by the apparent simplicity of the yaml configuration format, the toml more verbose format is probably better for the configuration of the site. I keep using a yaml heading for the posts and pages only. The one for the post you are reading looks like this:

---
date: 2023-01-12
title: Building the site with the Hugo static site generator
description: The journey to building a static web site using ...
tags:
 - blog
 - hugo
slug: 2023-01-starting
---

To use toml, replace the --- signs at the top and bottom of the zone of text with +++.