Home

You Should Make Your Own Site Generator

September 2025

Everybody Knows

I make my own site generators1. Mentioning that to a web developer is a sure way to get them to suck air through their teeth.

It's common knowledge: Building your own site generator is a fool's errand. There's tons of great tools out there. Making your own is a waste of time.

Sometimes, that's true.

Sometimes, it's bullshit.

Finding Purpose

I've yet to discover anything that's independent of its context. Making your own site generator is a perfect example.

  • Are you building a site that needs to Just Work?

    Use WordPress or any of the big players in the JavaScript framework world.

  • Are you working on your personal site or screwing around with an idea on a subdomain2?

    Why not write some HTML and CSS by hand? Or, you know, build your own site generator.

De-Creeping Scope

Off-the-shelf site generators are like JavaScript frameworks. They have tons of features. Most of which aren't needed most of the time.

YAGNI3 rules apply when making a generator. Don't add functionality until you need it.

Start Moving

Here's how to get started. Make this directory structure:

.
├── content
│   ├── _templates
│   │   └── main.html
│   └── index.md
└── docs

Use this for the contents of the content/_templates/main.html file:

<!DOCTYPE html>
<html>
  <head>
    <title>PAGE_TITLE</title>
  </head>
  <body>
    PAGE_CONTENT
  </body>
</html>

And this for content/index.md :

---
title: My New Site
---

# Welcome

This is my new site.

Now, parse the contents of:

content/index.md

use it to populate:

content/_templates/main.html

and output the results to:

docs/index.html

Great Success

Congratulations! You just made a site generator.

Use the site you're building to guide your next moves.

Maybe:

  • Walk the content directory and copy anything that's not a .md file (images, css, etc...) directly to the output folder.
  • Process any .md files and make corresponding .html files in the output folder.
  • Use a template: key in the front matter of .md files to choose a different template to wrap the content.
  • Create lists of links from sub folder to show indexes of blog posts, etc...
  • Add a template engine instead of doing a find/replace on strings.

The Charm

I'm a fan of the idea that software doesn't find its stride until the third version.

A similar number applies to early learning curves. The first few times doing something is mostly figuring out what the hell is even happening. You need a few reps under your belt before things stop feeling overwhelming.

I've found that to be as true with site generators as with anything else. Make a few throw-away prototypes to get your head around the process. Then, try one For Real. You may find it's something your into. Common knowledge be damned.

~a

end of line

Endnotes

I first started making my own site generators because of a typo. I'd been using Next.js for my site. One night, I found a typo. I fixed it in my markdown file and published the site. Everything broke.

Some dependency had changed out from under me. The site no longer compiled. It took an hour to figure out what happened.

That type of issue goes away with my own generator. It doesn't change unless I change it.

Another benefit. No more chasing the latest, greatest framework. My site is twenty years old. I plan on having it for at least twenty more. After switching frameworks eight or ten times, I never want to have to do it again.

It's been a few years now, and I'm more than happy just tweaking my tools whenever I want to change things.

I should mention, if I was making a big, complicated site, I'd use a framework. But, that's not what my sites are.

My current site generators are for static sites. I'm working on a separate API server to add some dynamic bits. Of course, you could roll everything into one as well.

Don't set out to overhaul your site with your first generator. Pick a small project and use a subdomain for it. Here are some ideas if you need one.

When you're ready to move on to your main site, don't worry about duplicating all the functionality in the first iteration. Just get the content to show up first. Polish there there.

You'll want a local web server with hot-reloading. You can add that into your SSG, but do that later. Use something like Browsersync to get started.

I'm using a folder named docs for the site output directory. That's what GitHub uses for GitHub Pages. You can make a repo from the folder that holds the content and docs directories, ship it to GitHub and use GitHub Pages to host the site for free.

Of course, if you're not using GitHub Pages you can name the output directory anything you want.

Footnotes

1 ⤴

I'm writing a big static site generator called Neopoligen that uses a custom file format called Neopolitan. That's not the type of generator I'm talking about in this post. I mean things more like my current Simple Site Builder.

2 ⤴

That time when my mind opened to all the possibilities that subdomains offer.

3 ⤴

Some folks say "You aren't". I was raised in the south. So, it's "You ain't" for me.