Go to content
Why I chose a static site generator to build my portfolio website and what I learned along the way.

As a digital professional, there is always one little-discussed and unfortunate truth we don’t often talk about: one’s own website often gets delegated to the bottom of the priority list.

This is the position I found myself in until very recently. I built my personal portfolio website in 2019, having built and rebuilt it a couple of times since 2017. But I never had the free time to rebuild it and have it reflect my current capabilities until the tail-end of 2022 when I was, at last, able to find some time to do so.

When evaluating my options for the rebuild, I found the best approach was a static site generator, something I had never used before. My static site generator of choice was Gatsby as it has an integration with WordPress’s GraphQL API.

I chose the static site generator approach because my portfolio site was going to have content that wouldn’t be updated very regularly, and I wanted it to run fast and smoothly, as I wanted its main purpose to be a place for my blog to live.

What is a static site generator?

A static site generator is defined by Cloudflare as “a tool that generates a full static HTML website based on raw data and a set of templates”.

So what does that mean? Basically, it means that the files for a website generated with a static site generator are just regular HTML and CSS, meaning your browser doesn’t have to wait around for all the files it needs to render the webpage, as it already has access to everything from the get-go.

In practice, this manifests as using a tool such as Gatsby or Eleventy to write templates for how content should be displayed in templating languages such as Nunjucks (a templating language similar to Symfony’s Twig in PHP) or React’s JSX.

This templating language then gets interpreted by your tool of choice and translates it all into normal HTML which gets served to the client side (the bit you can see as an end-user).

You can think of a templating language as the foundations of a building, the pillars and rafters that keep your house standing and the segmented areas that make it so you have individual rooms inside that house.

What about the content?

When a site is built with a static site generator, there are usually a couple of options you could have for where your content lives.

Your content could live in the same root directory as your template files, which you could write in a language like Markdown (using .md files) or straight Nunjucks (or whatever language you’re using as a templating engine) code.

In this way, the template files (written in Nunjucks or one of the many templating languages Eleventy supports) act as a blueprint that a static site generator uses to determine how to display the content you put in your content files.

Alternatively, your content could be hosted somewhere else, like in a WordPress or CraftCMS install, in which case your project is provided with the endpoint which essentially gets plugged into your project, making it accessible to your template files. This is known as a headless approach.

Okay, but why would I use one?

That’s a great question! There are many reasons why, in certain cases, a static site generator is a better option to use. Some of these include:

  • As a statically generated site already has all of the content it needs when it’s built, no requests are being sent back to the server, resulting in lower vulnerability to cyber attacks.
  • Another benefit of the site already having all of the content it needs is that load times are significantly faster, leading to an overall better user experience.
  • The use of version control means that if something goes wrong on a site, both the content and template files can be rolled back to a previous version, eliminating the risk of conflicts that would take a site down if the content and templates didn’t match up.

Why you may not want to use one

Although there are many benefits to using a static site generator, they’re not a one-size-fits-all solution to any project.

For one, dynamic functionality is not easily implemented on a statically generated site. For example, if you’re building an e-commerce site you would likely need to implement more complex functionality, such as the user having their own account on your site, having a list of things they’ve collected in their cart, and having a way to make a payment to you for the products they want to buy.

This kind of functionality often requires calling external APIs (like using Stripe or a similar service for payments) or entries in a database which is difficult to do securely on a statically generated site.

It’s also common for a statically generated site not to have its content provided by a CMS like WordPress or Craft which is an easier solution for clients. Even if a CMS is used to provide content (a feature well supported by Gatsby for example), updates to that content can only be reflected on the front-end once the site has been rebuilt, meaning changes aren’t immediately visible.

Conclusion

As static site generators are being worked on and developed, they’re becoming a more and more attractive and convenient option for developers and customers alike when they want a website with simple / rarely changing content. I for one look forward to diving deeper into using them and finding the best ways to do so.

If you want to start using a static site generator yourself, some of my recommendations are as follows:

  • Eleventy is a great alternative to using a CMS for your content, as its use of Markdown together with its support for many different templating languages make content entry a breeze.
  • Gatsby is a great option if you already know your way around React. It also has a fantastic built in Image Optimisation tool that makes serving accessible, sharp and low-file-size images easy.
  • Jekyll would also be a great option, as it can be hosted free on and powers GitHub Pages.
  • Hugo’s focus on making content management as easy as possible along with its community-built library of themes makes it a solid option.
  • VuePress although I haven’t looked into it personally, it looks like a Vue developer would feel at home in this SSG.

Each of these has clear and easy-to-follow docs that make getting started with them easy.