What is static site generation and why use it?

A long time ago, on a server far away

I own this domain name since more or less 10 years. Initially, I used it to access my personal server with a friendly name. One day I decided to serve a personal homepage on the www subdomain. At the beginning, this page was really simple. It just contained links to my different profiles on the web (Twitter, Github, LinkedIn). It didn’t contain any CSS (except the font) and not a single javascript line. It was handwritten, and I never updated it.

I never updated nor I backed it up. Until I lost my server due to an unrecoverable hardware failure. Shit happens. I had absolutely no backup and all my scripts (essentially Systemd and some configuration files) were gone. I lost everything. Everything including my marvellous handwritten index.html.

Reboot

I decided to change my approach of managing my personal server. No more dedicated server where I hosted every service I used (an nginx to serve the webpage, a traefik proxy to handle SSL with Letsencrypt, a PostgreSQL database, a Redis server, a Gogs server, a Miniflux instance, a Wallabag instance and a few other services).
I changed to host only the services I wanted to run myself, on a cloud service which self recovers from failures and relying on managed solutions for other services.

That included finding a way to serve a simple website that I could be able to easily evolve and redeploy.

I wanted to take opportunity of the forced reboot to add a few features to my website:

• a simple homepage,
• an image section (as photography is one of my many passions),
• a blog section,
• a page displaying my CV,
• an about page

Writing pure HTML for all these pages was not a viable solution. There was few constraints that I fixed :

• Not having to maintain the site except when managing content, that excluded self hosting full blown CMS like Wordpress or Ghost which I would have to update regularly to prevent security vulnerabilities,
• I wanted to be able to decide where my website is hosted, from a raspberry pi under my desktop to a cloud provider, and be able to quickly migrate from one to another, that excluded relying on managed CMS like the one previously mentioned,
• I wanted to be able to customize my theme, but also to have on the shelf themes,
• and finally I wanted it to be fast while remaining simple, because I don’t have a lot of content to publish.

Enter Static Site Generation

CMS have the advantage of allowing non technical people to easily publish content on a website at the price of some architectural complexity :

• managing a database with users (deal with security) and content that you have to backup, and ensure it remains up so your website remains available,
• handle updates and, if you are lucky, load, that means you have to work on performance of your website (if you are interested about optimizing Wordpress, my former colleague Colin wrote, in french, a series of post on how he did it on his website)

A few years ago, a tool became popular because it allowed to create websites without relying on CMS, this tool is Jekyll. It was called a static site generator.

But what does it mean? A website is basically a set of HTML, Javascript, CSS, images and other media linked by hyperlinks. The idea behind static site generation is to consider that most of the content of a website is static, so it can be generated as static files that can be deployed on any web server only when it is modified. This is exactly what I needed for my website.

Jekyll had a huge community, and was supported by Github Pages, but it had, in my opinion 2 drawbacks:

• it was a bit complex to install, as it was written in ruby,
• it was quite slow (which in my case, however, may not have been a problem as I have only a few pages)

By that time, I was playing with Go and a quite recent project draw my attention: Hugo. It was a static site generator that promised to overcome the two drawbacks I found in Jekyll:

• it was a single binary, so it was simple to install, and portable (or at least multi OS/architecture)
• it was fast. That is even their catchphrase “The world’s fastest framework for building websites”, and in my case, it takes only 1s to generate the website, including assets minification and image processing. We’ll talk about it in the third post of the series.

The project was young but promising. It lacked features compared to Jekyll, but it was enough for me. I played a bit with it, in order to understand how it worked, and so when I decided to remake my website, I chose to use it.

How does Hugo work?

It is really simple: Hugo takes your content written as static markup files (md, adoc, rst, html…), applies the theme and writes the static HTML, JS, CSS and media files in the output folder (public is the default). Then you just have to chose where you deploy your site by copying those files on a web server. It could be a Raspberry Pi running Nginx or Apache, your domain name free hosting like gandi, an application in the cloud, Github Pages, or an S3 compatible service. You decide.

Content management is decoupled from content generation. Traditionally, with static site generators, you use source code management software like git to manage versioning of your contents collaboration and the workflow (staging/production, etc…) of your website. Using git can be frightening for non technical users, but we’ll see that it can be hidden so you only use it directly if you want to. Or you can even not use it at all (I don’t recommend it, but as previously said, you decide).

As for content versioning, content editing is not managed by Hugo. You have the choice to directly edit your markup files with a text editor, or to rely on a more advanced editor, be it a local application like HokusCMS, or a managed cloud service like forestry or Netlify CMS (which may be more a javascript library interacting with your git repository hosting API and providing a UI on top of it).

You really chose your experience, from modifying your markup using your favourite text editor, and a bunch of scripts to build and publish your website on your server to a fully managed approach using Netlify, Github/Gitlab/Bitbucket and Forestry. And you start one way and if you decide to change, you can do it anytime. You never depend on a given service, and the configuration of the different services is generally a set of static files, so they are versioned like the rest of your website. If you make a mistake in your configuration, you can recover a previous version, you can delete a file or modify it by hand.

Which advantages?

There are many advantages to this approach:

• it’s fast & resource efficient: the pages are generated once, so when a user requests a page, it is only downloaded. No need to regenerate on each request in case something was modified in the database.
• it’s reliable: with a full blown CMS, you have (at least) a web server running an application (and most of the time, its plugins) and a database. Each of these parts can fail. With a static site, you only need a webserver, so you reduce the points of failures.
• it’s secure: no user management, no plugins to update, no database to secure, only a bunch of HTML/JS/CSS files.
• it’s scalable: you just have to copy the files on multiple servers, no need to manage a database under load or to setup a complex caching policy. It can be easily integrated with a CDN.
• you don’t have to sacrifice the contributor experience thanks to the various services supporting static site generators (and Hugo in particular) but you don’t have to use them if you don’t want to.

This is great for a lot of websites, from personal blogs like this one to really popular websites like letsencrypt or 1password support. However, there is an area that is not covered by static site generators: user generated content such as comments for example.

Jamstack to support dynamic content

Until now, we focused on static content. This is the major part of most of the websites, but when you need to deal with dynamic content (comments, likes, ratings, etc…), a static site generator won’t be sufficient. This is where Jamstack comes.

Jamstack is an acronym to make echo to Lamp stack (that stands for Linux, Apache, MySQL, PHP) which is the most frequent stack when running CMS like Wordpress or Drupal. Jamstack stands for Javascript, API and Markup. We already talked about the markup which is the way to write static content. The use of Javascript and APIs allows adding a dynamic part to your websites.

You need comments? You can integrate disqus, or an open source solution like isso (or its Rust implementation risso), remark42 or commento.

You need a search engine? You can rely on Algolia or a solution based on Elasticsearch or even a pure frontend solution. As your content is static, your search index is static too, so you can build it at the same time you build your website, and load it via javascript. You can find an example here.

Conclusion

As we’ve seen in this post, Jamstack and particularly static site generation is a great solution to build a website, be it a small personal one or a really popular one.

In the next post of this series, I will explain how to create a site with hugo, and present the tools I use to edit, version my content and publish my site. Then in a third post, I will explain the advanced hugo features I used to optimize the performance and get a great lighthouse score.