https://arne.me/articles/write-your-own-ssg

Skip to content

Arne Bahlo

Articles // Weekly // Projects // Contact

Why You Should Write Your Own Static Site Generator

Posted on November 3, 2023 from Frankfurt, Germany

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 is powered by my own SSG^1. 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
where 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 loose 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 to build something dynamic^2 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
choose 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
favourite programming language has a Markdown parser and a templating
engine.

For Rust I chose these crates^3:

  * 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!

Update: There's some discussion about this article happening on
Lobste.rs and Hackernews.

 1. Static Site Generators, in case you didn't make that connection
    yet. -

 2. Heresy! -

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

(c) 2021 - 2023 Arne Bahlo