Conceptual Article
An Introduction to Static Site Generators
Introduction
There are a number of software and tools used to create websites. One tool that is fast becoming a mainstay is called a Static Site Generator (SSG). A SSG is an application that automatically creates the HTML, CSS, and JavaScript files necessary to render a website. SSGs have gained popularity because of their flexibility. It can be used as a stand-alone tool or deeply integrated into a web architecture of your choice.
To outline the underlying web technologies that power SSGs and the features that make them useful, this article will explore various concepts as they relate to ‘static,’ ‘site,’ and ‘generator.’
Static
When a user views a page on a website, a request is made to a web server. The web server responds back with a specific file based on that request.
For example, say a user requests a page on a traditional or dynamic website. The server might need to query a database, send the results to a templating application, then finally generate the HTML file to render to the browser. This page is generated, on-demand, each time a request is made in this architecture.
Conversely, on a static site, the requested files already sit on the web server. This is what is meant by the term static: the files used to render the site are unchanging because they already contain the HTML, CSS, and JavaScript code. There is nothing to convert, generate, or transform on demand because they were generated before the page request.
To be clear, a static site can still be interactive. Things like JavaScript code, CSS animations, video and audio elements, and data formats like JSON are still supported and can run as normal on a static site. The only difference is that the files themselves are generated in advance rather than generated on demand.
You can think of a landing page or a blog post as examples of a static site. On the other hand, a live sports page or a comments section are examples of dynamic websites. For dynamic sites like these, you need a server or an API call to perform additional processing in order to render an element to the user correctly. You can read about the rendering spectrum to better understand how websites use a variety of techniques to reveal content to users.
Site
On any site, you need a way to organize and create content. Static site generators offer a streamlined way to accomplish this task. With a SSG, you can create and organize your site structure, while also having direct access to the content. One of the integral technologies common to many SSGs to help manage all of this is called a template engine.
Template Engine
A template engine is software that creates templates for common elements that appear across your site. Instead of hard coding repetitive HTML for each page on your website, a template engine assists in creating these elements for all your pages. For example, if you have a header and footer that are required to be on every page on your site, you can write this code once and apply it to the pages with template code. You can also use variables and expressions to build or replace values within a template.
Bear in mind that many SSGs let you choose your templating language, while some come with a frontend framework and templating language already selected for you. Template engines like Nunjucks, Pug, Liquid, and Blade offer you different ways to create templates.
Here is an example of a base template in the Nunjucks template engine:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Your Website</title>
</head>
<body>
<header>
{% block header %}
This is your header content
{% endblock %}
</header>
<div id="content">{% block content %}{% endblock %}</div>
<footer>
{% block footer %}
This is your footer content
{% endblock %}
</footer>
</body>
</html>
You can think of a base template as a container of placeholders. The {% block %} tags are blocks of template code. These can contain content or be left empty in order to be filled or overridden by child templates. Notice that each {% block %} tag has a variable name appended. For example, nested inside of the <header> HTML tag, there’s a {% block header%} tag that specifies that this block is named header. You can name this whatever you’d like, however it is best practice to use descriptive variable names in order to avoid confusion.
Template engines perform some heavy lifting to create these reusable templates that are then turned into HTML. These template files are usually placed in a directory called layouts or templates. Because templates are meant to be reusable, you won’t often write content directly within your template files. For content, you can create what are called Markdown files.
Markdown
Markdown is a markup language that is used to add formatting to plaintext documents before being converted to HTML. Although not a full replacement for writing HTML, Markdown can help you write and structure your content without worrying too much about HTML tags.
For instance, if you need to create an unordered list in HTML, you have to create an <ul> tag, then nested within, are your list elements wrapped with the <li> tag. In Markdown, you can create this list with an asterisk *.
<ul>
<li>Thing 1</li>
<li>Thing 2</li>
<li>Thing 3</li>
</ul>
* Thing 1
* Thing 2
* Thing 3
Many SSGs allow you to write all your content in Markdown apart from the encompassing code base. This way, you can focus on writing content instead of code, although you do have the option to write plain HTML in a Markdown file. These files are usually referred to as content files and are typically stored within a content specific directory. Your content will be rendered accordingly when paired with the power of your templates and the metadata used in front matter.
Info: You can learn how our custom and open-source Markdown engine powers and formats the content on DigitalOcean’s Community site.
Metadata and Front Matter
Another powerful tool in the SSG toolbox are languages that assist in configuring and formatting metadata. YAML, TOML, and JSON are the languages used to define metadata within the front matter of your content files. Front matter is the structured data that describes or defines attributes about the content. You can also use this data to apply a specific layout from your templates. This data usually sits at the very top of any given content file.
For example, with front matter you can define a title, an author, provide a brief description of your content, and use a specific layout from your templates:
---
title: Front Matter Matters
author: Author Name
description: Write out your description here
layout: base.html
---
This example uses the YAML language to define the contents of the page. The three hyphens --- at the top and bottom encapsulate your front matter metadata. Without these hyphens, your metadata will not be functional. In practice, you can include more or fewer metadata elements. Paired with a templating engine and Markdown, your content will be rendered to a page according to how you’ve structured your site.
Structuring your front matter can become increasingly complex as your site grows. Though it is beyond this article to explain the intricacies, you can use front matter to create links, tags, and more to customize your site.
Generator
After structuring and creating content for your site, what’s left is to build it. During this build process, all your assets – including things like CSS, images, JavaScript, metadata and more – are entered into a pipeline and pieced together. These assets are typically minified, transpiled, compiled, bundled, then ultimately served to a user as static files.
Minification
When your assets are minified, an application removes white space, indentation, new lines, long variable names, and code comments in order to keep the file as small as possible. This is sometimes referred to as “uglifying” your code, since it removes much of the formatting that makes it easy to read. Although it may look odd, your code still functions the same when minified.
The following is an example of some CSS code prior to minification:
html {
box-sizing: border-box;
}
*,
*::before,
*::after {
box-sizing: inherit;
margin: 0;
padding: 0;
}
body {
background: seagreen;
font-family: sans-serif;
}
.wrapper {
padding: 1rem;
border-radius: 1rem;
display: flex;
}
Here is the same code, but minified:
html{box-sizing:border-box}*,::after,::before{box-sizing:inherit;margin:0;padding:0}body{background:#2e8b57;font-family:sans-serif}.wrapper{padding:1rem;border-radius:1rem}
Minified files are not meant to be edited. Since the minified code is contained in a new file, it is the one that gets used on the production site. Instead, if you require edits, edit the original unminified file, re-save and re-compile the minified file, and replace it on the server to reflect your changes.
Bundling
It’s common practice to write code in separate files during development. This allows you to use smaller, more manageable chunks of code rather than a single monolithic file containing all the code for your site.
For example, you might have multiple scripts and modules that call each other when a button is clicked. You might also have multiple CSS stylesheets for the different pages and elements on your site. Furthermore, it may also be true that your scripts and CSS depend on each other for functionality. When your site is in production, having to request all of these resources individually can slow down your site, as each adds a little latency to the rendering process. This is what bundling is designed to solve.
Code bundling is the process of combining and merging code into a single file. For instance, if your JavaScript functions, modules, and components are contained in separate files, bundling merges them into one JavaScript file. The same is true if you write your styles using a CSS preprocessor, like SASS, where the code is separated. Bundling will also compile these files into a single CSS file.
In the end, bundling, like minifying, is an optimization process. Instead of requesting multiple scripts or stylesheets, by bundling the browser may only need to request a few.
Different bundlers use different processes to merge your code together. There are quite a few bundlers out there and each SSG is usually integrated with one. rollup.js, Parcel, and webpack are examples of bundlers. SSGs like Gatsby and Next.js use webpack to bundle their assets.
Transpiling and Compiling
The transpiling and compiling process essentially turns your code into files that any web browser can read and execute.
In general, a compiler is an application that translates and converts a higher level programming language into a lower level programming language. For example, a compiler could translate C code into 1’s and 0’s, machine code, in order to run a program.
A transpiler is a type of compiler that translates code from one programming language to another equivalent programming language. As an example, the transpiling process could mean turning code written in the Typescript programming language into the JavaScript language. Since web browsers don’t understand Typescript code, it needs to be translated into JavaScript in order for a browser to execute it.
The popular JavaScript application called Babel is an example of these concepts in practice. Babel does its best to ensure that JavaScript code is readable in old and modern browsers alike. Another example of this is Autoprefixer. It detects newer CSS features and inserts the proper fallbacks for wider browser support.
Whether you’re working within a legacy code base or with the newest syntax, the transpiling and compiling process interprets the code for the browser to achieve the deepest possible browser support so that users can interact with the page as you intended.
Build Command
When you’re finished creating your site, you can type your SSG’s specific build command into your terminal. This command is configured to minify, transpile, compile, bundle your code, as well as perform any other tasks required to serve your static files. For example, if you’re using the Gatsby SSG, you would type in gatsby build into your terminal to initiate the build.
During the build process, you may notice the terminal outputting the build’s progress. This includes specific details about how the files are being processed. You may also encounter error messages during this process telling you where the failure occurred. If everything runs successfully, the terminal will tell you after it is finished with the build.
During a successful build, the static HTML, CSS, and JavaScript files needed to render the site are placed in a public or dist directory. The exact name of this folder will depend on your configuration.
Note: If you’re interested in a deeper explanation into this process, Gatsby’s great documentation details what happens during its build process.
After building your site, you may end up with a site structure that is similar to this:
your_project_root
├── node_modules
├── public
├── src
│ ├── css
│ │ └── styles.css
│ ├── js
│ │ └── script1.js
│ │ └── module.js
│ ├── images
│ │ ├── dog.jpg
│ │ └── cat.jpg
│ ├── _includes
│ │ ├── partials
│ │ │ └── about.html
│ │ └── layouts
│ │ └── base.html
│ ├── posts
│ │ ├── post-1.md
│ │ ├── post-2.md
│ │ ├── post-3.md
│ └── index.html
├── .your_SSG_config.js
├── package.json
├── package-lock.json
├── README.md
└── .gitignore
Please note that, depending on the SSG you use, your file structure may include different files and directories. Though there can be a significant amount of work up front when creating a site with a SSG, the payoff is static files that will be served, without additional server processes, creating a faster loading experience for your users.
Beyond Static
Static site generators by themselves are powerful tools. Coupled with other web technologies, they can blur the line between static and dynamic. SSGs play an integral role in the Jamstack ecosystem. Like a LAMP or MEAN stack, the Jamstack is another way to create and architect a website or web application. It uses the power of SSGs to create static HTML and utilizes JavaScript and API calls to connect to backend services and databases.
A SSG can also work in tandem with a CMS. This other model of development is called headless CMS. With a headless CMS, you have a way to store data, have a graphical user interface to interact with for content, and an API endpoint to connect to. In this model, you’re removing the presentation layer — the “head” — from the backend management system. A SSG fills this missing role for the presentation layer. For example, an editor can use the CMS interface to create content which is then stored on the database. A developer can then access that content via the API endpoint and create a view to display the content to users.
SSGs are also extensible. With different plugins and modules, your SSG can become something a bit more than its initial offering. For example, in Eleventy, you can use a plugin to optimize and resize your images and even utilize serverless functions to create dynamic pages. Depending on your needs, a SSG can grow in complexity and functionality, while still outputting static files.
Conclusion
In this conceptual article, you’ve learned about some of the underlying technologies that static site generators use to create a website. With this information, you now have a better understanding about how static sites are created with a SSG.
If you’d like to know more about creating a site with an SSG, we have a tutorial series on the popular SSG Gatsby.
If you’re interested in Eleventy, we also have a tutorial on How to Create and Deploy Your First Eleventy Website.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
author
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Get our biweekly newsletter
Sign up for Infrastructure as a Newsletter.
Hollie's Hub for Good
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.
Become a contributor
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.
