There are lots of static site generators (SSGs) out there these days, coupled to a lot of different headless content management systems (CMSs), using various development frameworks, running with various templating languages, and making life seem a lot more complicated than it probably needs to be. But you may still be scratching your head and asking, what is a static site generator?

With that in mind, this article aims to explain in a more general way what’s going on in a typical SSG these days. Because even though there are a lot of different names flying about, there are some key general elements and processes that are common pretty much across the board.

What Is a Static Site Generator?

Let’s start at the beginning: a static site generator (SSG) takes some “source” files that describe a website and, processing those files, creates the files needed for the website that was described.

I think of it as basically a compiler. You have some source code, the compiler runs, and out comes a binary executable that you can run on your computer. I realize that, in the current web world, developers work largely with interpreted languages, not compiled ones, but bear with me.

The SSG, in other words, is an application that reads some files, processes their contents, and then writes some new files, with the new files constituting a web site. This process is the heart of the matter, the place where the magic happens, and so on.

The Website

The SSG creates a website and that website is a website that you could (sort of) say has no moving parts. This is why people talk about “static” sites.

Now, the simplest website is one that is made up entirely of a single HTML file. This is nothing more than a text file with some special “markup” tags and it is very fast and very simple for a web server to send off to a browser that has requested the page across the internet.

All the web server has to do is grab that one file, stick some delivery headers on it, and send it on its way. This can happen with almost instantaneous speed if the internet connections involved are fast ones.

This speed is one of the key benefits of static sites, even though they aren’t as simple as a single HTML file. Generally speaking, though, they are nothing more than HTML files, CSS (style) sheets, possibly the occasional javascript file, and whatever images are displayed on the site. They are all 100% ready to deliver whenever they are requested, with no additional processing needed.

Why the Build?

The reason the world needs SSGs is because there are generally lots of pages of content that need to go into a website. We don’t really want to have to create HTML versions of all the content—and there’s a pretty simple reason why this is.

I’m old enough to have coded a couple early commercial sites on the web. Every page on those sites was individually created in HTML. If there was a menu at the top of the page, it was there it was copied from some other page and pasted there. If you wanted the currently selected menu item to be highlighted, you had to make a version of the menu with the selected element set in reverse text (or whatever the treatment was) that was specific to the page you were working on.

A site with a hundred copies of the same header, except for which selections are highlighted, is a mistake waiting to be copied and pasted. There are typically lots of repeated elements on web content pages (footers, anyone? Sidebars?), and hand management is a fool’s errand.

The world could have moved to SSGs then and there, twenty years ago, but what happened instead was that web servers became integrated with databases. In this scenario, the server would assemble the elements of each requested page as it was requested. The header would be connected to the newly fetched main page content, then the footer retrieved and tacked on, then the final page shipped off to the user.

This is still how most web sites work and such web sites are said to be dynamic.

An SSG does the same assembly that a dynamic web server might do, but it does it before the website is served to users—it does the page creation in advance.

Thus…

So, an SSG needs to get the headers, get the sidebars, get the footers. It needs to get the main bits of content for each page, along with the titles and subtitles, anything that needs to be on each page.

So there’s the actual generator, the SSG, and there’s some kind of store for page content, and there’s some way of describing what each kind of generic page will look like in HTML.

In a simple example, there’s the SSG called Eleventy. It takes page content (in the simplest setup) in more-or-less plain text files called “Markdown files.” It arranges the content from those files with guidance from a templating system called Nunjucks. A diagram might look like this:

In the case of Gatsby, the SSG is Gatsby, the simplest data source is the same markdown that Eleventy uses, and the templating is handled by functionality that comes with the React JavaScript framework. Same diagram, different labels.

Jekyll is yet another SSG, in this case written in Ruby. Again, the simple way to feed content data to it is once again Markdown, and the templates for how the content fits on the final HTML pages is a system called Liquid.

If you take a look at the ridiculously long list of SSGs maintained by Netlify at https://jamstack.org/generators/, you’ll see that each listing mentions the language the SSG uses and which template systems it supports. Looping back to Eleventy for a second, it actually supports several other templating languages beyond Nunjucks: Liquid, Handlebars, Mustache, EJS, Haml, Pug, and JavaScript template literals.

Beyond Markdown

If you want to capture the content of a blog entry, Markdown is a nice, clean way to do it. SSGs tend to support it as the entry-point content data source. It was sufficiently prevalent in the early days of SSGs that when Netlify was looking for some kind of term to encapsulate all the different approaches to SSGs being created and coined the term “jamstack,” the M stood for Markdown. (The J stood for JavaScript and the A stood for APIs. A person could argue pretty convincingly that none of these three selections were accurate, but it did at least spell something recognizable with “Jam.”)

There are lots of other options beyond Markdown, including using the same sorts of databases that dynamic web sites use. This isn’t the article to dive into all those options.

There’s also more involved than just plain-old HTML. There need to be CSS files, frequently there need to be JavaScript libraries to handle user interface elements that click and move and so on within the client browser window, and the SSGs that use the React framework play some pretty fancy tricks with swapping components in and out on the fly at the client browser.

But the basic setup is that the SSG is an application that takes content data from sources like markdown files or headless CMS services (such as Contently and Sanity and Ghost and lots of others), uses templates to create the layout of the output pages, and when it’s all said and done, creates a static site.

Of course, there are some other bits that you may be curious about beyond this simplest reduction of what makes an SSG what it is. For one thing, you may be wondering about the API part of the original JAMstack term (these days, Jamstack is used predominantly as a term that doesn’t specifically stand for anything, but instead refers to the entire ecosystem). That’s coming up shortly.