Meet Hugo, a static page generator

This very website kaszkowiak.org was created using the Hugo static page generator.

The project is divided into several subdirectories, the most important of which are:

• content: Markdown content of pages, one file - one subpage. The internal folder structure corresponds to the page structure.
• assets: files that require processing before generating the page, such as: SASS, minification, bundling.
• layouts: the layout templates that are used to generate individual pages.
• static: static files copied without modifying, such as images, pure CSS, JS, etc.

The workflow is extremely convenient. Hugo has a built-in server that automatically generates the website once it detects a file change and refreshes the browser. The speed is astonishing - on my PC it takes ~15ms to update the content, while generating the entire website (including converting SASS to CSS) takes just a second!

Deployment is also easy, especially on platforms like Github, Gitlab, or Netlify. Pages written with Hugo integrate very well with git.

Why exactly Hugo?

First of all: the ease of making changes. Adding new pages and posts isn’t a problem at all. You only need a simple text editor for editing. There’s no need for a CMS and the markdown posts are very portable.

Other advantages are speed and low resource usage. At the moment of writing this article, Hugo with its built-in server uses only 60 MB of memory. The page generation speed means that I can see the changes in my browser immediately after pressing CTRL+S. From a hosting stance, a static page generated by Hugo can be used anywhere - it’s just HTML. You don’t need database access nor a code interpreter, which opens up a wide range of free hosting solutions, such as Github Pages or Netlify.

I see Hugo as a tool for programmers only, as it won’t come in useful otherwise.

A rough diamond

Hugo is a great tool, although it’s hard to get started. I’ve encountered some issues that might be worth mentioning:

• Hugo has significant gaps in the documentation, making it hard to find information on some topics. For example: the more we use Hugo templating, the more whitespace we will find in the generated HTML code. The solution is simple - by surrounding the {{variables}} in the brackets with an {{- extra dash -}}, Hugo will remove the unnecessary whitespace around the brackets. This was also hard to find in Google - if you’re searching under “hugo remove extra new lines”, then you won’t find anything in the official documentation. It’s a rather small thing, but it’s a good example.

• Compiling SCSS requires downloading the Hugo Extended version. Starting my adventure with Hugo, I copied a snippet converting SCSS to CSS, which additionally requires the NPM postcss module. I received a rather vague error message, which in no way indicated that the module was not installed. According to Github Issues this ambiguity has been corrected, but I hit this in the latest version as well.

• Hugo does not have a built-in default theme. When you run the “hugo new site” command, you only get an empty directory structure. In the starter guide, the authors recommend downloading the Ananke theme using git. I consider this a significant obstacle for beginners - the recommended theme is quite extensive and it is hard to start modifying it without sufficient knowledge. A much better solution to start with would be a simple Hello World: with two subpages, comments in the code for what the file is used for, and a basic header / content / footer structure.

You can follow my blog with any RSS reader!

Maciej Kaszkowiak

Software Developer @ X-ONE

Passionate about many subjects: AI, sport, music, travels, programming 🚀