A comic version of a white guy with short hair, smiling.

Why You Should Write Your Own Static Site Generator

· Frankfurt, Germany · HN, Lobsters

I’ve used a lot of static site generators in the past, and they all have their own features and quirks, but most importantly, you have to architect your website to match what the framework expects.

Since yesterday, this website has been powered by my own SSG1. It’s not meant to be reusable, it’s just normal code—parsing and generating files for this specific website.

And oh boy do I love it.

Why??

When Vercel released Next.js 14 recently, some friends I’ve talked to were still on Next.js 12 and really felt the pressure to upgrade to not fall behind even more. This made me think about the longevity and robustness of my website, and so I decided I don’t want to depend on other people’s decisions and run after version upgrades I don’t care about.

And even if your content is Markdown and media, almost everything around it needs to be updated when switching frameworks—sometimes even when upgrading. When I used Astro before, I wanted to statically generate OG images and, after some research, managed to build it and even wrote an article explaining how. You lose all of this custom logic.

Plus, you get to choose your own stack. Want to write your content in AsciiDoc? No-one can stop you!

I know what you’re thinking, and you’re right, it’s way more work than using something that already exists. But it’s also so much more fun. You can do anything with this, and you don’t need to read documentation or try to understand other people’s architectural decisions—just start writing code!

Okay, tell me how you did it

After contemplating building something dynamic2 for search without JavaScript, I decided to stay with a static site. It’s faster, and you don’t have to worry about security or stability. And of course, I chose the best programming language on the planet, Rust (my beloved). Wait, come back, this is not a Rust post!

A static site generator mostly needs to do five things:

  1. Convert markdown to HTML
  2. Render HTML templates
  3. Compile CSS
  4. Generate RSS feeds
  5. Generate a sitemap

And of these, you might not even need the last three. Surely, your favorite programming language has a Markdown parser and a templating engine.

For Rust, I chose these crates3:

  • comrak and gray_matter for parsing Markdown and the frontmatter
  • maud for compile-time templates
  • grass for SCSS compilation
  • rss for (you guessed it) generating RSS feeds
  • quick-xml for generating the sitemap

Once I got the tools I needed, I just started writing software. I built something to parse my content, something to render all the different templates I needed, something to generate the RSS, something to generate a sitemap and…that’s it, really!

And when it’s time to add OG images to this website, I can choose the best libraries and just build it.

What now?

I hope this article left you either validated that rolling your own is not worth it, and you want to keep using a framework, or interested to see what’s on the other side.

If you’re in the latter camp, you can check out the source of this website to get some inspiration. But most importantly: Choose a tech stack that excites you and have fun!

  1. Static Site Generators, in case you didn’t make that connection yet. ↩

  2. Heresy! ↩

  3. If I had chosen Go, I probably would’ve looked at goldmark, goldmark-frontmatter, html/template and encoding/xml. ↩