Static sites with Hugo

Read in 6 minutes ·

At a time when Content Management Systems solutions, like Wordpress or Joomla had an associated cost and required a considerable amount of maintenance, static site generators such as Jekyll, together with free hosting services like Github Pages, were created to help users set up, host and run their website in a matter of minutes.

It was not unusual in hosted Wordpress solutions to have to update their Wordpress instance or 3rd party plugins from time to time, even for those who just wanted to have a blog or to build an online presence by showcasing their CV.

Static site generators fixed these issues while also making it easier to backup, offering more flexibility and requiring fewer security concerns, which makes the user focus on the content and not so much on the infrastructure around it.

Hugo

Written in Go in 2013, Hugo is another static site generator but with a focus on speed and flexibility. With a lot of different themes to choose from, free or paid, Hugo provides many different tools and defines guidelines on best practices for theme creators, so that end-users can switch between themes without having to introduce significant changes in the codebase.

As an example, most themes support out of the box integrations with tracking platforms like Google Analytics or 3rd party comment services like Disqus.

Project

Recently I have worked with Hugo in two different projects, with this blog being the first one and an engineering documentation website at my workplace the second, both with different requirements.

Sharednode

Moving Sharednode to a static site required the following:

  • Support for multi language;
  • Support for several menus;
  • Support for different authors;
  • Support for content exporting;
  • A responsive design;
  • A minimalistic design.

Minimalistic and with two predominant colours, the ezhil theme seemed to be the closest to the Sharednode brand, even though it required a few tweaks.

Even though Hugo provides support for themes to be multilingual, not all are ready for it, so it was necessary to add a menu button to the top-right corner of the theme with the language codes in which the content was also translated.

Sharednode was initially created to be used by different authors, so it was essential to keep that feature. Even though the theme did not support this either, it was achieved by adding a new author field to the front matter1 of each post and then referencing it in the post’s HTML page.

Posts can be written in markdown, isolated from the theme implementation, which makes it straightforward to export them or reuse elsewhere when needed.

With ezhil having a responsive design, just as most of the themes available online, all the initial requirements were now met.

Engineering documentation

The engineering documentation has a different purpose compared to the previous project. In this case, the site had been built with the whisper theme, and it needed to start supporting multiple menus so that it would be easier to add and discover content.

It was important to move from a single menu with a sidebar (with further navigation) to four menus, each with their sidebar and their submenus.

Hugo generates each menu by scanning through each folder inside the content folder, the root of all content, and then each sidebar by getting the title of each post inside that folder.

To have a second layer of navigation in the sidebar, I added an extra field in each post’s front matter that is verified during the sidebar generation, and if present, a tab space is printed.

For interface and visual tweaks, like updating colours and replacing assets, it was necessary to create a folder in the root of the project, with the same name as the asset’s folder in the theme, so that those values get overridden during the site generation.

This was necessary because the project sets up its theme through a git submodule, so whenever the site gets deployed, local changes in the theme are not applied remotely.

Thoughts

There is a trend of people that recently is migrating from medium since content paywalls were introduced, which gives an edge to authors that opted-in and does not promote the ones that don’t.

Even though Sharednode doesn’t have an audience big enough for it to be a concern, moving from medium to a static site occurred mostly because of the multi-language support as well as the flexibility to visually and functionally customise.

At this point, I already had tried to set up a site in Jekyll a few years before, but because I failed at doing so, I decided to go with Hugo this time. Plus, I had seen Steve Francia doing a presentation with Hugo and saw how fast it was to set up and run and deploy.

Setting up the base for Sharednode wasn’t as simple as I thought, but after watching the video tutorials, it became pretty straightforward. Customising it, however, took slightly longer.

While setting the navigation is done mostly through Hugo configurations and general assumptions, customising the UI and adding extra functionality like multi-language is highly dependent on the theme that one uses.

After both experiences, I am still not sure what to think about the organisation of the official documentation since it can be quite good at times but also a bit confusing when you are just starting to work with static sites since the documentation is organised at a technical level and not so much on functionality. This organisation means that users go online and ask about how can they implement the feature that they need.

I have noticed that Hugo does not seem to support any content searching out of the box, so in a blog-style site, this could potentially be limiting for visitors. Similarly, in the creator’s side, I decided to prefix the date of publishing to each post’s filename so that content filtering in the future becomes possible.

Statically generated sites are certainly not the solution for every content creator but with the use of standard text formats like markdown and it’s inheriting exporting nature, together with theming flexibility and feature extensibility, makes them an option worth considering.

QA

João Junceira (@jmjunceira)
Software Developer at Teckro

1. How do you see the role of generated static websites in today’s industry?
Static websites are around for a long time since the Web started. I think they are getting popular thanks to Git-based hosting. They are useful to write documentation, web pages to promote a product, blogs or even some corporate page.

2. Have you used any in the past?
I have a Hugo page with my CV and personal project. Once created a blog to test the features. It’s quite easy to use and seems to be really fast to publish.

However, Hugo might not be the most friendly tool for front-end developers because it’s written in Golang. Since this are power-users that like to customise their tools.

3. In which other scenarios would you use Hugo?
Have a corporate static page or page to promote a product. Any other technical purpose such as documentation. Basically anything that doesn’t need to query a backend.

Resources

  1. “Front matter allows you to keep metadata attached to a post, i.e, it define the title, data, weight, etc. ↩︎

If you like this post, follow me on Twitter or Telegram