brennan.day
Static Site Generators for Beginners
I've been writing technical tutorials on my website since I started it last November, but this thread asking about static site generators for beginners on 32-bit Café made me realize I've never made a proper tutorial regarding SSGs from the ground-up basics. This post initially began as a reply to that thread, but I realized I had enough to say to fill an entire blog post. I hope this is helpful to anybody who has been interested in static-site generators but has found trying them out to be difficult, obtuse, and with a lot of friction.
I'm someone that grew up using SSGs, going from editing the HTML on my Tumblr straight to setting up a blog with Jekyll when I was a teenager around 15 years ago now. While I would say I'm knowledgeable, being able to communicate and articulate that knowledge (particularly to beginners) is another skill entirely, and one I want to cultivate more. Hopefully I do a good job with that here!
## Prerequisites
Let me start off by saying that, if you're brand new to web development, I do **not** recommend beginning with a static-site generator. If you're making your first website (or ten), I really recommend writing out the HTML and CSS yourself—this removes a lot of the abstraction that occurs with SSGs.
Nearly all SSGs assume you know the fundamentals of HTML, CSS, and sometimes JavaScript. They also assume some familiarity with programming concepts, the terminal, and usually version control such as Git. You certainly do not need to master all of these before making a site with an SSG, but knowing what is going on underneath the hood will make the inevitable errors much less mysterious.
### Free resources
I would work through the resources below in the order I've listed, creating your own sites along the way:
* **HTML:** HTML for People is a friendly introduction written for people with no previous coding or web experience. MDN's HTML learning module is a more technical reference for when you want to get to aspects like semantic elements and accessibility.
* **CSS:** MDN's CSS styling and layout modules explain things like the box model and CSS layouts. If you prefer interactive exercises and projects, freeCodeCamp's Responsive Web Design course covers HTML, CSS, accessibility, and responsive design. (Responsive meaning mobile-friendly in most cases)
* **JavaScript and web fundamentals:** MDN's JavaScript module is a good addition to its HTML and CSS lessons. And freeCodeCamp's JavaScript curriculum is another free, interactive option.
* **Programming fundamentals:** CS50x is Harvard's free introduction to computer science. Computational thinking, algorithms, data structures, functions, variables, conditionals, and loops. You don't need to know all of this, but the first few weeks of the course would give you a good foundation.
* **The terminal:** MIT's Missing Semester teaches the shell, command-line environments, editors, and debugging. Check out the introduction to the shell.
* **Git and version control:** Pro Git is a free online book that starts with the command line and basic commits before moving on to branches, remotes, and hosting. Reading this on a Kobo during my commute to college was how I learned git myself.
* **Markdown and YAML:** The Markdown Guide is good for seeing how symbols are used for writing in Markdown. For YAML, the official YAML 1.2 docs are more detailed than you need, but the introductory explanation is useful.
* **Checking your work:** To see if your HTML has any errors, the W3C Nu HTML Checker is a good resource to detect any invalid markup.
MDN has a "Learn Web Development" resource as a single place to learn HTML, CSS, JavaScript, and browser fundamentals. There are others, like the Odin Project, web.dev, w3schools, and more.
Understand that you don't need to know everything. You're doing this as a hobby, it's fine to make mistakes or do things in unorthodox ways that guides don't recommend. The important thing is not to finish every course before starting—build tiny sites as you go along with what you learn. Each step will give you more competency and functionality to add to your projects.
## Definitions
Next, before I jump into the history of static sites, I want to define some often-used terms you'll see when reading static-site documentation and guides, since a lot of this jargon is typically not defined well. Most developers will simply think you already know all of this stuff by default.
### The Web and the Generator
**HTML (HyperText Markup Language)** is the base document of a webpage, it's a language of structure and semantics. Headings, paragraphs, links, images, lists, and stuff like that. HTML is not a programming language, so it doesn't make decisions or repeat actions by itself.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My First Page</title>
</head>
<body>
<h1>Hello, world!</h1>
<p>This page has a <a href="https://brennan.day">link</a> and a list:</p>
<ul>
<li>HTML gives a page its structure.</li>
<li>There's no CSS yet, so this is all default styling.</li>
</ul>
</body>
</html>
Save that as `index.html`, open it in a browser, and you get a real page—see it live here.
**CSS (Cascading Style Sheets)** changes how HTML is rendered. This is how you add specific and unique colours, spacing, fonts, responsive behaviour, etc.
body {
font-family: Georgia, serif;
max-width: 35rem;
margin: 2rem auto;
padding: 0 1rem;
background: #fff2ce;
color: #02005d;
}
h1 {
color: rebeccapurple;
}
Add that inside a `<style>` tag in the `<head>` and the exact same page now looks like this.
**JavaScript** is the most commonly-used programming language in web browsers. It is frankly rather janky, but it's what we have to work with. It can add behaviour and interactivity to your site, but it is rarely ever necessary and can slow down and bloat a webpage. I personally recommend using it sparingly.
const button = document.querySelector("#surprise");
button.addEventListener("click", () => {
document.querySelector("h1").textContent = "JavaScript did this!";
});
With a `<button id="surprise">` added to the page, that script does this.
An SSG can also use JavaScript, for example, to run its build process or its template code. In 11ty, you can even write an entire template as JavaScript:
// hello.11ty.js
module.exports = function () {
return "<h1>Hello from JavaScript!</h1>";
};
* **Static** means that a server returns a file as-is, without generating a new page for every request (typically a user visiting the page). A static page can still contain JavaScript and can still be changed later, as “static” only describes how the page is delivered, not whether it is immutable or boring.
* **Dynamic** means that something generates or changes the response at request time. A traditional content-management system might query a database and assemble a page whenever someone visits it. A store website would need to keep a database of inventory that changes based on when people add an item to their cart and purchase, for example.
* **Static-site generator (SSG)** is a program that takes source files (like Markdown content, templates, configuration, and assets) and builds a rendered site of HTML, CSS, JavaScript, and image files from them that can be hosted as a static site.
* **Build** is running the generator's command that turns those source files into output files.
* **Source files** are the files you edit, such as Markdown posts, templates, stylesheets, and configuration.
* **Output files** or **built files** are the finished files produced by the build, often placed in a folder such as `_site/`, `public/`, or `dist/`.
* **Local server** is a web server running on your own computer. A development server lets you view the built site at a local address (like `localhost:8000`) and can rebuild it when you save a change to a source file.
### Configuration and Data
* The **Configuration file** is a file containing site-wide settings—it can include things like a site's name, base URL, menus, output directory, RSS options, etc. Different SSGs use different filenames and formats, including `config.yml`, `hugo.toml`, and `eleventy.config.js`.
* **YAML** (usually pronounced “yamel”) is a human-readable data language often used for configuration and front matter. It represents values such as strings, numbers, lists, and key-value mappings. Indentation in YAML is significant, so a stray space can cause a build error.
* **Key-value pair** really just means here's two parts to each config option, such as `title: My post`. In YAML, a collection of these pairs is called a mapping.
* **Parameter** or **option** is a setting passed to a command or configured in a file. For example, `--serve` is an option in a command shown later in this guide.
Here's an 11ty site settings file (`src/_data/site.json`), where you edit the user-facing details of your site:
{
"name": "My Cool Blog",
"description": "Where I write about whatever interests me.",
"author": "Your Name",
"url": "https://example.com",
"language": "en"
}
Every key-value pair becomes a variable your templates can use: putting `{{ site.name }}` in a layout prints "My Cool Blog", so changing the name here updates it everywhere at once. This is one of the neat features of SSGs, and it means you only have to change the name in one place. Other SSGs put the same idea in `config.yml` (Jekyll) or `hugo.toml` (Hugo) instead.
### Templates and Content
* A **Template** is a reusable file containing the structure of a page, with various placeholders.
* **Layout** is a template for a larger page shape, containing all of the following: the document language declaration, `<head>`, header, main content area, and footer.
* **Partial** is a smaller reusable fragment, such as a navigation bar, header, footer, or post metadata block. “Include” is the instruction that inserts one file or fragment into another.
* **Templating language** is the syntax used to insert variables, loop over data, and make decisions inside templates. Liquid, Nunjucks, and Go templates are examples.
* **Conditional** is a yes-or-no instruction in a template, such as “show this element only if the post has an image.”
Here's a simple layout (`_includes/layouts/base.njk`, written in the Nunjucks templating language) that uses a few partials:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ title }} | {{ site.name }}</title>
</head>
<body>
{% include "partials/header.njk" %}
<main>
{{ content | safe }}
</main>
{% include "partials/footer.njk" %}
</body>
</html>
And the partials are fragments of HTML:
<!-- partials/header.njk -->
<header>
<a href="/">{{ site.name }}</a>
{% include "partials/nav.njk" %}
</header>
<!-- partials/nav.njk -->
<nav>
<a href="/">Home</a>
<a href="/archive/">Archive</a>
<a href="/about/">About</a>
</nav>
<!-- partials/footer.njk -->
<footer>
<p>© 2026 {{ site.author }}</p>
</footer>
When a post's front matter says `layout: base.njk`, 11ty wraps it in this template: `{{ content | safe }}` is where the rendered post body goes, and each `{% include %}` puts a partial in place. Edit the header once and every page on the site updates. This is the copy-paste problem SSGs solve.
* A **Content file** is a source file, like a page or a post, typically written in Markdown. In SSGs this is often Markdown, but it may also be HTML, plain text, or another supported format.
* **Markdown** is a rather well-known markup language that uses punctuation symbols to represent headings, links, lists, emphasis, and other document structure. A generator converts this into HTML.
* **Front matter** is a small metadata block at the beginning of a content file, commonly enclosed by two lines of `---`. It can contain a title, date, tags, layout name, or draft status.
* **Blog-aware** means that a generator is specifically built for posts. It can usually sort them by date, and can generate specific pages like an archive, tags page, and RSS feed automatically.
* **Metadata** is information like a post's title, author, publication date, tags, description, canonical URL, or chosen layout.
Here's a single 11ty blog post (`posts/my-first-post.md`) that uses all of the above: front matter metadata written as YAML key-value pairs, Markdown content, and a little templating language.
---
title: My First Post
date: 2026-09-22
tags:
- posts
- cats
layout: post.njk
draft: false
---
Welcome to my blog! This paragraph is **Markdown**.
This post is called "{{ title }}".
{% if draft %}
This sentence only appears while the post is a draft.
{% endif %}
The front matter between the two `---` lines is metadata 11ty reads before rendering. `layout` tells it which template to wrap the page in, `tags` makes it part of the `posts` collection, and `date` is how the blog-aware sorting knows where it belongs. Everything below the second `---` is the content file's body.
### Validation and Publishing
* **Hosting** is the service or computer that stores the output files and makes them available on the internet. Hosting is separate from writing the site, and also separate from version control.
* A **Backend** is the server-side code and infrastructure that runs behind a website. It handles authentication, forms, business logic, or database queries. A purely static site does not need a backend to serve its pages.
* A **Database** is similar to a spreadsheet that software can query and update. A traditional dynamic blog stores posts, comments, and settings in a database. Anytime you see `SQL`, that's a database.
* **FTP (File Transfer Protocol)** is the protocol used to copy files between computers, commonly from your computer to a web host. It is one way to publish a site.
* **rsync** is a command-line program that synchronizes files between locations. It can copy just the files that were modified, which makes it useful for uploading a built site to a server.
* **Link validation** is a nice quality-of-life feature that checks if any links go to missing pages. Some SSGs do this during the build, and others require a plugin or an external checker.
### Version Control
* **Version control** is a system for recording changes to files over time so you can inspect history, compare versions, restore an earlier state, and collaborate with other people.
* **Git** is one specific version-control program. It runs locally on your computer and can record the history of a project without requiring a hosting service.
* A **Repository** (or **repo**) is a folder/project directory with a history managed by Git.
* A **Commit** is a saved snapshot of changes in a repository, typically with a message describing the change.
* **Remote** is another copy of a repository. Typically, there's a remote hosted version of the repo on Codeberg, GitHub, GitLab, or a server you control.
* **Push** is a command that copies commits from your local repository to a remote. And **Pull** retrieves commits from a remote and incorporates them into your local repository.
* **Git hosting** is a service that stores Git repositories and may provide extras such as issue tracking, code review, or automatic builds. This includes GitHub, GitLab, Codeberg, etc.
* Git hosting is convenient, but it's good to remember that it is not the same thing as Git, and is not required to use Git.
Here's what publishing a new post with git looks like in the terminal:
git init # turn this folder into a repository (once)
git add posts/new-post.md # stage the file for your next commit
git commit -m "Add new post" # save a snapshot with a message
git push # copy your commits to the remote
## A (Very) Brief History of Static Site Generators
Now that we have all those definitions out of the way, let's actually talk about the context of static-site generators.
SSGs didn't start with Jekyll. The idea of separating your writing from the code goes back to the mid-1990s. A really early example is HSC ("HTML Sucks Completely"), an HTML preprocessor Thomas Aglassinger released in 1996. The term "static site generator" wouldn't exist for another decade or so, but HSC already had includes, conditionals, and link validation.
For most of the late 90s and 2000s, the mainstream answer to "how do I blog" wasn't static. It was hosted, dynamic services like Blogger, LiveJournal, and Open Diary. Or full-stack tools with databases and a backend, like WordPress. The one exception was Movable Type, a Perl-based platform Ben and Mena Trott built in 2001 that did something clever: every time you published through its web GUI, it rebuilt your blog into plain static HTML files behind the scenes. You weren't using the terminal, but the output was static. Movable Type was one of the first tools to bring the benefits of a static site for people who never typed a `build` command.
Nanoc was built by Denis Defreyne in 2007 after finding all Ruby-based CMSes ran painfully slow on the 96MB VPS he was using. Nanoc introduced layouts, page metadata, Markdown support, and plugins. It was a year later, in December 2008, that GitHub co-founder Tom Preston-Werner released Jekyll, out of frustration with complex blogging engines like WordPress. Jekyll built on Nanoc's ideas and added two things: front matter (the YAML block of metadata at the top of every content file) and being "blog-aware" out of the box, meaning you could put Markdown files in a folder and it would turn them into a blog with no extra setup. GitHub launched GitHub Pages alongside Jekyll as free static hosting, and that combination is a large reason why Jekyll popularized SSGs for many, including myself.
Everything since has really been reinvention and iteration on the same idea in different languages. Some prospered and some failed. Octopress (RIP) and Middleman iterated on SSGs in Ruby. Pelican and Hyde are Python-based and Laravel-based SSGs, respectively.
In July 2013, Steve Francia released Hugo, written in Go and compiled to a single binary. This was far simpler relative to Jekyll: there was no entire Ruby environment you had to install, or gem versioning you needed to wrestle with, and Hugo is fast enough to render thousands of pages in seconds.
Eleventy (11ty) was created by Zach Leatherman in late 2017 as an agnostic alternative to Jekyll, using JavaScript and NPM instead. Whereas Jekyll required you to use the Liquid language, 11ty lets you use:
* HTML `*.html`, Markdown `*.md`, WebC `*.webc`, JavaScript `*.11ty.js`, Liquid `*.liquid`, Nunjucks `*.njk`, Handlebars `*.hbs`, Mustache `*.mustache`, EJS `*.ejs`, Haml `*.haml`, Pug `*.pug`, TypeScript `*.ts`, JSX `*.jsx`, MDX `*.mdx`, Sass `*.scss`, and even Custom `*.*`
Jamstack.org has a full list of different SSGs, if you happen to have experience in a specific programming language and want to leverage that.
Something important I want to note is that some of these generators haven't been updated in years. And guess what? That's actually usually fine! The "static" part of SSGs means there's no backend or database to hack. Another benefit is that security isn't something you need to worry about. Did your favourite SSG add genAI slop in the newest update? Just never update. Your SSG will continue working and building your site the way it is now indefinitely. Hurray!
## Why is git always recommended?
Aside from programmers just finding git to be the status quo default, I think a lot of the assumptions regarding git are due to the fact that Jekyll, the first popular SSG, began as a GitHub-specific project. Using GitHub (or Codeberg, or GitLab, etc.) answers the question "where do the files live?" which is in the repository. Neocities/Nekoweb answer this by you uploading your files onto the site.
When you use something like Codeberg Pages or GitLab Pages, a lot is happening underneath the hood, and every time you upload or edit a file, it _is_ being committed and pushed with git, you just aren't running the commands yourself manually via the terminal or GUI interface.
If you're self-hosting, then the answer is just your own computer, somewhere like the `/var/www/html` folder if you're on Linux. If you have a Tildeverse account (which is yet another rabbit hole), then your files would live on the publicly-shared computer. Here's my Tilde.town site for example, where I use the command `rsync` to upload my local files from my computer to the tilde.town computer and they're hosted automatically.
There are two different things git is actually doing here, and they're easy to conflate.
* Version history (so you can undo a bad edit or see what changed and when)
* Hosting (somewhere for the built files to actually live).
You don't need git for either one. `rsync`, an FTP client, or dragging files into a browser upload window all work fine for hosting. And you can take care of backups for your own small personal site instead of worrying about version history. Git just happens to solve both problems at once and for free, which is why it often becomes the path of least resistance.
## Theory vs. Practice
On paper:
* You take Markdown files in a `posts/` folder
* They're rendered with a template in a `layout/` folder
* Which has modules of HTML in `partials/` like `header.html` and `footer.html`
* And there's probably a `config.yml` file in the root or something similar where you can edit the parameters of the site, like the name, colours, etc.
* That `config.yml` handles site-wide settings, but most SSGs also give each individual post its own small metadata block, usually called front matter, sitting at the top of the file between two lines of `---`.
* That's where a single post's title, publish date, and tags live, separate from the global config, so the generator knows how to sort and label a page without you having to name it `"2024-03-14-my-post-title.md"`.
In practice, it is far more complicated. The process of taking all of the above and outputting it to a rendered static site (say, into a `/_site` folder) requires a programming language to process it.
Most popular SSGs _try_ to make this simple: you run a command like `hugo build` or `npx @11ty/eleventy --serve` in the terminal, and that will do the above.
(That `--serve` flag will start a local server on your computer, and regenerate the site anytime you edit the source files, rather than just building once and quitting. That's what makes editing a static site feel nearly as immediate as editing a live page.)
Platforms like Netlify (or the self-hosted Coolify) essentially have a restricted remote computer that will detect which SSG you're using and run the appropriate command automatically, and your `/_site` is then hosted at `yoursitename.netlify.app` similar to how you'd manually upload your own HTML files to Neocities and have your site hosted at `yoursitename.neocities.org`
There are other platforms that do the same (that I would not personally recommend): Vercel, Cloudflare Pages, GitHub Pages, and surge.sh.
But all of the above has _a lot_ of assumptions built-in: you've done everything perfectly, _and_ the programming language used to build the site installed correctly, _and_ you know how to use the terminal. This XKCD comic on average familiarity comes to mind.
If you have a typo anywhere important that breaks something (which could be as innocuous as an extra comma somewhere) the entire thing is fragile enough to break either during the initialization or build process, and the error message is designed for the programming language, _not_ the SSG. Which means you'll get a very technical output. Here's an example of a failed Netlify build my site had recently simply because I had a trailing comma in the file that stores JSON.
If you don't have the stubbornness that masochistic programmers (like me) have, it's very understandable that you see the above error and go "fuck that" and just handroll your HTML, or use a CMS, or just don't make a site at all. That last one is the most heartbreaking to me.
## My Starters/Themes
The way I learned was by taking pre-made starters/themes others have made (as others in this thread have recommended) and tinkering with them. Then, I started to get proficient enough to make my own. If you want to get to know an SSG, I hope I can recommend these, as they have good-enough documentation/guides and are designed to be instructive for beginners:
* **IndiePaper** is a Hugo starter I made with all the IndieWeb stuff built-in (microformats2, h-card, etc.), where you put your posts in the `/post` folder and edit the `hugo.toml` file to customize.
* **11ty-Indie-Web-Blog-Starter** is an 11ty starter I made from the ground-up based on my own site, where you put your posts in the `/posts` folder and edit the `site.js` file to customize.
* **Watery** is a Jekyll starter I made ages ago, where you put your posts in `/_posts` and edit the `_config.yml` file to customize.
All of these themes are minimal and plain (and kinda ugly) because the actual CSS styling and design aspects are left to the user.
## Other (Simpler) Alternatives
All the SSGs I used above are very popular ones, but there are many more relatively simple options out there. Like barf and bashblog and kiki.
* **barf** (blogs are really fun) is a shell script by btxx that's only 170 lines. It's forked from Karl Bartel's blog.sh. There's no front matter and no templating, you just write Markdown files, run `make build`, and it produces a `build/` folder you rsync to your server. It generates valid RSS automatically, runs natively on Linux, macOS, and OpenBSD, and the stylesheet is four lines of CSS. You can read the README or view a live demo.
* **bashblog** is a single ~1,000-line `bb.sh` script with zero dependencies, using base Unix utilities such as `date`, `grep`, `sed`, and `head`. Carlos Fenollosa built the first version in 2011, writing about it on his own blog, and it's still maintained today. You download `bb.sh`, put it in a public folder on your server, and run `./bb.sh post` to start writing. It handles drafts, tags, Markdown, and RSS out of the box, no installation step at all. If you want more features, there's a community fork called bashblog-ng.
* **kiki** is by vga256 and self-describes as "a tiny homepage construction kit with a small footprint". It uses PHP rather than shell, and it can run as either a live dynamic site or generate a static one, and also double as a public wiki or (in preliminary form) a Gopher hole. It's shareware and free with a footer credit, or pay $15 CAD and get additional features. It's 1,500 lines of hand-written code, zero JavaScript and zero external dependencies. It's a great option if you have a host that only allows PHP and doesn't give shell access.
And here are a few others:
* **ssg** is Roman Zolotarev's POSIX-compliant shell script. It's the inspiration for several of the others on this list; there's a Python rewrite called pyssg.
* **sw** is a minimal web framework written in C, and the fork **simple-static** strips it down further into what its README calls "the simplest static site generator I can think of."
* **makesite.py** is a Python equivalent of barf and bashblog. It's under 130 lines and built by Sunaina Pai around the idea that "the code is the documentation." The idea being that there's nothing to configure that you can't just read and edit directly.
None of these alternatives have anywhere near the features that Hugo or 11ty have, but as a result, they also don't have the complexity.
Finally, you may also be interested in making a blog in Gemini:// which is an entirely different rabbit hole I've been getting into recently, and eliminates the need to generate anything at all.
## Conclusion
I use SSGs because if I were to handroll the HTML for my site, then I'd have to copy-paste the header and footer for every page, and SSGs take care of that kind of thing. I go into more detail about this in my IndieWeb ladder article.
To me, I don't care how you webweave or what method you use to get your work online, as long as you're participating and trying, I think you're succeeding! Give my WEBMASTER@ manifesto a read if you haven't already. Static-site generators are just one of many ways to get into webweaving, and I certainly hope you join us—however that looks.
