Why You Should Write Your Own Static Site Generator

I&#x27;m not sure I&#x27;d advocate for writing a static site generator, although I&#x27;m certainly guilty of writing a few myself.<p>Instead I always encourage people who are trying to start blogging to do the writing first. Figure out a workflow that works for you - what time of day you prefer writing, what editor, do diagrams naturally come up in your thought stream, etc. It&#x27;s way easier to get this workflow dialed in when you&#x27;re doing things locally since the switching cost between solutions is that much lower.<p>Only when you know that you A) enjoy writing and B) have something worth sharing should you invest the time in translating your workflow to something that can deployed. That might mean writing your own SSG - that might mean just spinning up a wordpress blog.

It&#x27;s a fun project to try out new tech, but you have to acknowledge that you&#x27;re doing it for fun rather than any sort of necessary reason. It&#x27;s like when you build a game engine and never get around to doing the hard part: building the game.<p>It&#x27;s a procrastination time hole that mostly just distracts us from the harder, less concrete, less fun thing we supposedly set out to do in the first place. It keeps us from shipping real shit.<p>e.g. Quit dicking around with your SSG and write the damn blog post already. The hard part of writing something worth reading is not your tech stack.

&gt; [...] but most importantly you have to architect your website to match what the framework expects.<p>I guess that&#x27;s what a framework is about. You get some abstractions that make your life easier and you pay by buying into the concepts.<p>&gt; [...] some friends I&#x27;ve talked to where still on Next.js 12 and really felt the pressure to upgrade to not fall behind even more.<p>If the current version is doing its job, why update? It&#x27;s a SSG not a browser that connects to the internet.<p>So I disagree. I&#x27;ll not write my own and keep the existing one as long it&#x27;s not too much hassle.

For over 2 decades, my personal Web site has been generated from one big Emacs Lisp file (plus a filesystem tree of image and downloadable files).<p>Both the code and the text data were in the one file.<p>The code included features like rich syntax coloring source view of files (fairly unusual at the time) that were also downloadable, and calendar-based blog navigation.<p>Over time, the code changed a little, such as to convert from HTML tables to CSS with the same look.<p>Just the one file, in Emacs, was a very rapid and lightweight way to work. Imagine a code file that includes simple function definitions, like that below, and calls to those functions, passed a mix of static and generated data for the pages.<p><pre><code> (defun web5-write-html-file-format-sideheads (root-dir subdir leaf-fname title-list sections) (if (stringp title-list) (setq title-list (list title-list))) (web5-write-file root-dir (concat subdir &quot;&#x2F;&quot; (or leaf-fname &quot;index.html&quot;)) (web5-page-html title-list (web5-format-sideheads title-list sections)))) </code></pre> If I were doing it today, I&#x27;d probably do lots of Markdown files and a bespoke generator program, though that wouldn&#x27;t be quite as rapid to develop as the Emacs single file one was.

&gt; <i>Plus, you get to choose your own stack. Want to write your content in AsciiDoc? No-one can stop you!</i><p>I wrote a static site generator once. I used a Makefile and m4 macros!<p>Yes, it&#x27;s true: nobody could stop me. It&#x27;s much more debatable whether the &quot;you should&quot; part applies. I was just trying to get some common header and footer HTML into all pages of a site and do it with tools that were already installed on the hosting provider&#x27;s machine.<p>It worked. For some reason, the person who took over the site after me did not follow in my footsteps and keep using m4.

&gt; it&#x27;s way more work than using something that already exists. But it&#x27;s also so much more fun.<p>I&#x27;d say this person &quot;gets it&quot;. We spend waaay too much time bickering about what people &quot;should&quot; do, in my opinion.

I used various SSGs for a while but the SSGs kept having arbitrary breaking changes that took a while to debug. I switched to my own little Python script 6 years ago and have slowly evolved it since then. Hasn&#x27;t broken yet.

Call me crazy, but for my blog I just write HTML and RSS manually in a text editor.

I&#x27;ve written two static site generators... well one of them has a full blown UI (drag and drop, side panels etc), the other is a command line tool.<p>For the WYSIWYG tool I used craftjs and lexical, and ran into issues with both - bugs, difficulty doing things like having different alignment for mobile vs desktop. It was very brittle and it would be troublesome migrating data structures down the track. I&#x27;ve put 1.5 years into this (added my own k8s hosting on GCP too - also with its issues)!<p>The second command line builder took me a couple weeks to make a simple version of. I describe my pages, sections in JSON and render predefined erb templates. I scripted up deployment to Amazon S3, Cloudfront, and invalidate the cache after deployments.<p>It&#x27;s crazy I spent so long on the Saas version and didn&#x27;t get to a working website, and with the command line version now have a couple sites up!<p>It&#x27;s a cool experience to make your own site builder, definitely learn something each time you do.<p>Here are the sites I made:<p><a href="https:&#x2F;&#x2F;www.madebyhelena.com" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.madebyhelena.com</a> <a href="https:&#x2F;&#x2F;LouisSayers.com" rel="nofollow noreferrer">https:&#x2F;&#x2F;LouisSayers.com</a><p>(Helena is my partner, I remade her site which she had created on a different platform)

I wrote too (and still maintain) a SSG, it&#x27;s a fun exercise: <a href="https:&#x2F;&#x2F;github.com&#x2F;darccio&#x2F;zas">https:&#x2F;&#x2F;github.com&#x2F;darccio&#x2F;zas</a>

I see a lot of people building their own static site generators. There&#x27;s probably a lot of common elements to the process, right? We should abstract those commonalities into a static site generator generator, so that everyone who needs to write a static site generator doesn&#x27;t need to reinvent the wheel.

Lots of &quot;don&#x27;t reinvent the wheel&quot; comments here. But if you&#x27;re a developer, crafting a SSG for your own needs is a 2-3 hours project. Learning an existing one is roughly the same. But hey... it&#x27;s a good opportunity to learn by doing, and even later appreciate other SSGs.<p>My own SSG is Django+Distill.

Did an SSG last month.<p>I had used pelican before; but I wanted to get a better handle on using Markdown and Jinja libraries &quot;from the other side&quot; as well. I would have needed to adapt my file structure or write some code to let pelican scan my idiosyncratic hierarchy to generate the posts.<p>Turns out Markdown is easier to use on your own scripts, than it is to tweak its configuration in pelican; and Jinja is quite simple too. Getting to use the &quot;debug&quot; feature to dump everything available to a template is nice.<p>I haven&#x27;t bothered with RSS or sitemap yet, but i did do a nice calendar view render of my archive indexes; which i don&#x27;t think could&#x27;ve been easily wedged into pelican&#x27;s notion of how sites work. <a href="https:&#x2F;&#x2F;snafuhall.com&#x2F;news.html" rel="nofollow noreferrer">https:&#x2F;&#x2F;snafuhall.com&#x2F;news.html</a>

I have experienced both sides. First, I&#x27;ve written my own generator in Python (about 300 lines) but the code was not exactly maintainable and adding features like tagging was hard. So, I looked around and picked up Hugo. While I don&#x27;t like the template engine it was not too much work, to set it up and offered everything I wanted. But Hugo comes with braking changes all the times! Plus the Hugo developers don&#x27;t know what semantic versioning is, so you have to figure out whether a new release works with your configuration or not.<p>Now I&#x27;m on the verge to write my own generator again (probably in Kotlin or in Rust), because I&#x27;m tired of Hugo&#x27;s breaking changes and because I still don&#x27;t like the ugly Go templates.

A fun experiment I’m sure but it’s not a very convincing argument for writing your own generator. In the same way the author claims frameworks will change, so will the tools that power their custom solution and using a framework will take a fraction of the time to get going.

<p><pre><code> I know what you&#x27;re thinking and you&#x27;re right, it&#x27;s way more work than using something that already exists. But it&#x27;s also so much more fun. You can do anything with this, and you don&#x27;t need to read documentation or try to understand other people&#x27;s architectural decisions—just start writing code! </code></pre> Great argument for never writing your own SSG.<p>Back in the day we didn&#x27;t have SSG&#x27;s. We just wrote the html&#x2F;js&#x2F;css by hand, and then used the existing browser and web server features to keep it DRY. No frameworks, no generators, no complexity. It wasn&#x27;t fancy (or pretty) but it was simple and it worked.

I think the answer depends what kind of site you are targeting. For a clean and simple text blog it may actually be optimal to build something from scratch using building blocks you know well.<p>But for a larger site that might evolve and get more complex over time the DIY approach will likely hit the reinventing-the-wheel dilemma multiple times.<p>Its better to figure out which of the existing SSG&#x27;s has a programming model that fits your brain and simply learn it well so that you can extend it in any which way you like.<p>As a bonus, instead of yet another half baked ssg, you can contribute something back in terms of plugins, themes or other code and feel good about yourself.

I agree.<p>I don&#x27;t mean to say you should not share it. You constructed something good, you feel pride in your device, by all means share it with the world.<p>However static site generation is one of those simple fun rewarding types of program to make. The programing is straight forward, the results are linear with the input, that is, there is not a huge amount of boiler plate you have to wade through to see anything. Basic batch data transformation like this is the perfect environment to metaphorically &quot;putter around in the workshop&quot;<p>Nothing wrong with using someone else&#x27;s, but really, you should write your own.

Considering that a vast majority of people who decide to learn a static site generator never end up really developing their static site much beyond a few articles talking about their static site generation process, I think there is definitely more value in just going all the way and writing your own static site generator from scratch. The code is the true purpose, not the final output. And the thing about a static site generator is, once it works – you’re done. You can put the project away and move on to other common things like building a tile map editor, etc.

I fully support the idea that writing your own SSG can be not only a great learning experience, but also a chance to make your SSG do exactly what you want it to (and nothing more).<p>I&#x27;ve written a ton of little SSGs over the years, and every iteration I&#x27;ve learned what kind of features I really need, and which I don&#x27;t.<p>When I started working on the current version of my personal website (istigkeit.xyz), I also wrote a new SSG just for it. The program is called Hyphae[1], and it&#x27;s written in Ruby using the Kramdown markdown gem, and pretty much nothing else outside the stdlib. It works perfectly for me, and that&#x27;s all that matters (that being said, the code is up there, and licensed with the Unlicense, so anyone who finds it useful is free to use and abuse my clumsy code to whatever extent they want).<p>I&#x27;m a big proponent in the idea of writing personal software: that is, programs that are made by you, for you, and with no expectation that they&#x27;ll be used by anyone else. I think too often developers these days get caught up in trying to make their project be &quot;the next big thing&quot; in whatever domain it serves, but honestly sometimes it&#x27;s nice to just write something for yourself :)<p>[1]: <a href="https:&#x2F;&#x2F;gitlab.com&#x2F;henrystanley&#x2F;hyphae" rel="nofollow noreferrer">https:&#x2F;&#x2F;gitlab.com&#x2F;henrystanley&#x2F;hyphae</a>

I too had build my own static site generator. A buddy asked if he could use it to build some sites, so I invested in it being more polished. Put a REST API in front of the engine and file management, and then an AJAX SPA on top of the API. Over the years, it&#x27;s been used by a bunch of web sites - large and small. The largest was Longwood Gardens - which had hundreds of pages.<p>This was about 20 years ago now. Once it a while I consider refactoring&#x2F;resurrecting it. But I&#x27;ve not found the time.

when I made <a href="https:&#x2F;&#x2F;carefulwords.com" rel="nofollow noreferrer">https:&#x2F;&#x2F;carefulwords.com</a>, which is just a thesaurus that I wanted for myself*, I effectively had to make a static site generator, since it required a lot of preprocessing steps to get all the words linked to each other, word synonym lists, and word quotes assembled from various text files. And this article is right: you can just build it. I just put together some TS scripts over a couple weekends to smooth it all together (and then another day on top to make it fast). After that I can keep using and editing my weird bespoke sources to build my project.<p>If I had to use a static site gen to do the same thing, it probably would have taken a lot longer, or I might have had to do so much pre-processing or massaging of my data that I was effectively building a static site gen on top of someone else&#x27;s static site gen. And why bother with that? Of course if the project had any more complexity, I would benefit from stronger templating, and putting a static site gen layer after my own static site gen is probably exactly what I&#x27;d do. Just stitch them together, instead of trying to get my first-steps into someone else&#x27;s static site gen.<p>* I wanted one that has <i>lots</i> of synonyms, has some historic quotes to go with words, has autocomplete and unlike good old thesaurus.com it should focus the text box on load<p>The result being perfectly static means its perfectly fast. It also means there&#x27;s a lot of crude overlap - every page has the same HTML copied and pasted a million times. But that&#x27;s OK, it&#x27;s small, so it&#x27;s still faster.

Maybe don&#x27;t write a static site generator. Maybe just make a normal website made of individual HTML and other files that doesn&#x27;t require any &quot;generation&quot; at all. Static site generators are supposed to be for getting away from complexity but most of the time they just shift the complexity away from being attackable.<p>There&#x27;s no requirement for websites to be generated either statically or dynamically. The best websites are just files in folders.

I would ALMOST agree.<p>Five years ago I dove into using an ultra-light-weight framework called MetalsmithJS. It&#x27;s super minimal, but does what you need. I&#x27;d spent 10 years using the Drupal monolith, and did not regret the move. Yet it&#x27;s open-source community dried up, but mostly because the framework does what it claims and then stopped expanding!<p>Here&#x27;s a blog post... <a href="https:&#x2F;&#x2F;doublejosh.com&#x2F;post&#x2F;186193119278&#x2F;metalsmithjs-is-still-really-useful" rel="nofollow noreferrer">https:&#x2F;&#x2F;doublejosh.com&#x2F;post&#x2F;186193119278&#x2F;metalsmithjs-is-sti...</a><p>Then two years ago I needed a more robust SSR system based on React, so I went with GatsbyJS. It&#x27;s insanely mature and intuitive, but as we all know that community and business is now drying up too. But the framework is still great.<p>Now everyone sings the praises of NextJS, which can be used for SSR but is intended for applications and active server endpoints. But more complexity doesn&#x27;t mean better.<p>I&#x27;m keen to try other simple frameworks when the result is a static site. I may give <a href="https:&#x2F;&#x2F;www.11ty.dev" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.11ty.dev</a> a shot.

Just like a bunch of us here, I also wrote an SSG.<p>I setup a cronjob to fetch weather data and run the SSG to parse the XML and render a weather &quot;website&quot; on my VPS.<p>But for the blogs I&#x27;ve had&#x2F;have, I just use a pre-existing one (zola). There are hundreds of SSGs out there, why bother building yet another one if one already exists for transforming your preferred base doc (markdown, asciidoc, morse code, etc)

I didn&#x27;t realize this was so common. In my crazy days I wrote a SSG using only XSLT, so you wrote a big xml with the content and it would output a full site ready to upload.<p>It needed a specific XSLT processor as most couldn&#x27;t generate individual files, but it was nice that it worked with off the shelf software, so technically I didn&#x27;t write a single line of code.<p>(XSLT is madness, don&#x27;t attempt)

Absolutely agree, I did a fair bit of both and I really regret using the framework du jour.<p>I have a lot of websites (maybe more than 20) and they&#x27;re a mix of old version of next.js, hand rolled websites and some solid.js websites.<p>The solid.js sites are fairly easy to update - but it&#x27;s also very new (the oldest being 3 years) and I&#x27;m not sure it will stay that way forever. You just need one wrong decision from the fun guys at ECMA and frankly I&#x27;ve been burned already by commonjs vs esm.<p>The handcrafted sites from 10 years ago have some old and simple dependencies and they work fine. The next.js stuff is a horrible nightmare of different errors. Everytime I need to do a one-line change I get to do a nice debugging session. This is also a combination of the providers I&#x27;m using not having a fixed node version, but I&#x27;ve also found some dependencies breaking compat from one patch to another.<p>I guess the key takeaway is: use as little deps as possible.

I&#x27;ve written my own in (over the years and in order) PHP, Delphi, Ruby, Python, C#, Go, then C# again (after moving from Framework to Core) for serving my blog [1].<p>- It&#x27;s fun<p>- It improves with each iteration due to experience gained<p>- It&#x27;s great to have a sample project to create in any language you consider using as it&#x27;s a small yet realistic way to discover how that language works and what the ecosystem provides<p>[1] <a href="https:&#x2F;&#x2F;kcartlidge.com" rel="nofollow noreferrer">https:&#x2F;&#x2F;kcartlidge.com</a><p><i>As an aside I also quite like yak-shaving - which is why for my latest C# iteration and just for the pleasure of it I&#x27;ve written my own Markdown parser and am working on my own templating engine (bit like Razor, ERB, or PHP).</i>

I built one. I run a content website for a living so it was worth it. I wrote about why here: <a href="https:&#x2F;&#x2F;nicolasbouliane.com&#x2F;projects&#x2F;ursus" rel="nofollow noreferrer">https:&#x2F;&#x2F;nicolasbouliane.com&#x2F;projects&#x2F;ursus</a><p>The short version: text files let you use powerful tools, not just the WYSIWYG editor supplied with your CMS. Navigating markdown files in Sublime Text is incredibly fast compared to clicking around in a PHP admin area. I can even write blog posts with Obsidian on my phone.<p>It also means a very simple, very fast server that runs forever without maintenance. You don&#x27;t need much to serve static files.<p>Above all, it means source-controlled content and content branches. This is great for big changes that span multiple pages.

I recently had to nuke the Linux environment where I had my Jekyll environment finely tuned (Ran it on Debian WSL). Then I realised I had to reinstall Ruby, but the current Jekyll version (or the gems I use) uses a version that needs to lock OpenSSL at a certain version because of some breaking changes. Tried to lock the version in Debian and I was having a really hard time.<p>Then I realised I just could grab the latest Jekyll image from Docker hub and build my website with it. And just like that I was able to build my website without dealing with any ridiculous dependency.<p>So yes, you should write your own static site generator because it might be a tad easier than trying to install from scratch the dependencies of whatever generator you have chosen.

I had the same idea as you and rewrote my blog CMS. Initially it was very similar to yours, with Maud [1].<p>Then I started a little library for replacing Maud, for a better developer experience [2] (still looking for a better name).<p>The important thing for me is having fun in the process, my personal website is a sandbox for playing and experimenting :)<p>[1] <a href="https:&#x2F;&#x2F;anto.pt&#x2F;articles&#x2F;rust-server-components" rel="nofollow noreferrer">https:&#x2F;&#x2F;anto.pt&#x2F;articles&#x2F;rust-server-components</a><p>[2] <a href="https:&#x2F;&#x2F;github.com&#x2F;Pitasi&#x2F;rscx">https:&#x2F;&#x2F;github.com&#x2F;Pitasi&#x2F;rscx</a>

Another option that I’ve found worthwhile is to write a Jekyll Plugin, so you get a stable base for your SSG, and you can experiment with adding weird functionality on top.<p>For my news website, I needed to scrape some news from a third party API, and I just moved it to a Jekyll plugin so it embeds neatly into the website. Works quite well: <a href="https:&#x2F;&#x2F;github.com&#x2F;captn3m0&#x2F;news">https:&#x2F;&#x2F;github.com&#x2F;captn3m0&#x2F;news</a><p>Another place where it made sense to use SQLite as a data source, I wrote a Jekyll SQLite plugin.

Nah. I&#x27;ll stick with Pelican. It does what I want in a pretty straightforward way, and there are tons of themes and plugins available for it that <i>I don&#x27;t have to write.</i>

I&#x27;ve been very impressed with Eleventy:<p><a href="https:&#x2F;&#x2F;www.11ty.dev&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.11ty.dev&#x2F;</a><p>I find my lingering desire to roll out an SSG slowly fading.

I wrote one in elisp for publishing my blog directly from org-mode files in Emacs (because of course). It is super minimalist and works great for my specific use case.

I ended up writing my own because nothing did what I wanted (1 post per folder with all media inside the same folder, Wiki linking, partial rebuilds and various layout features). Never looked back, and today I just commit to my source repo and it goes and rebuilds and uploads only the pages that have changed (out of 9000 or so).

I did a very minimal version of this myself recently, and it was very fun! I don&#x27;t even have Markdown - I just write HTML and have a couple of helper Python scripts to update headers, generate boilerplate for images, etc. It&#x27;s nonscalable and not really for anyone else, but fun, easy to understand, and there is not much to go wrong.

I use a hybrid approach. Next.js is the base for my site but I use next-sitemap and a hand rolled content compiler (md -&gt; html -&gt; jsx) for feeds, meta tags, and generating every page I dont manually specify as a .tsx file.<p>I like having the flexibility to do either. Complete control in .tsx or just writing in .md. I would like to add .mdx eventually too

There is also a Static Site Generator written in Python. <a href="https:&#x2F;&#x2F;github.com&#x2F;ahui2016&#x2F;pyboke">https:&#x2F;&#x2F;github.com&#x2F;ahui2016&#x2F;pyboke</a>. I used this to generate my blog: <a href="https:&#x2F;&#x2F;yinan.me" rel="nofollow noreferrer">https:&#x2F;&#x2F;yinan.me</a>

This is so cool. I did the same last week with pure php without any dependencies besides icon, gd and rsync for deployment. Feels like I had sitting inside a LAMP prison for the last two decades. Now just some json files are my database. No fancy bullshit. Just handmade code and some templating. I feel freed like you.

I feel there&#x27;s something to be said about a static site with a simple PHP-based search function thrown in there. Perhaps it could have even the full site content pre-generated as a data structure in PHP, for keeping in memory. Could be just word-&gt;pageId mappings, if you want to keep it simple.

I wrote mine a couple years back and have been using it for a few blogs and anything I want to make a landing page for. Even built a mini game engine for it that loads up zip file games. Also added an editor and a backend for dynamic blogging and live reload.

These never come explaining Why html is to hard. Basics and ftp can be explained to a 12 year old in 10-20 minutes? I&#x27;d even argue (based on decades) that everything learned beyond the first 30 minutes is probably something you should not be using.

For Swift there’s <a href="https:&#x2F;&#x2F;github.com&#x2F;JohnSundell&#x2F;Publish">https:&#x2F;&#x2F;github.com&#x2F;JohnSundell&#x2F;Publish</a> which is a framework to create a static site generator. It’s really good.

Such a strange abstraction layer.<p>Thr author could have skipped a step and formatted using tags instead of markdown and published the html directly, with zero need for any generator. Using scp and html, like it was 1998.

I made a website that does all the markdown to html conversion right on the client and it still has great SEO. Apparently google and stuff will just index the markdown itself.<p>No compilation step needed.

I once wrote a static site generator in m4!! This was about 2002, and I discovered m4 while picking apart GNU autoconf. It was anachronistic (to say the least) even then.

I want to write my own SSG and probably will soon. My current site is built using Gatsby and oh boy it’s a lot more complicated than it really should be.

I wrote one and it&#x27;s the only software I still maintain and am proud of. I&#x27;m kind of inventing a new React like thing in it. It&#x27;s way cool.

I did write my own static site generator. Used gulp and used nunjucks and streamed a json file for content into the gulp build system...was 61 lines.

It&#x27;s something worth doing at least once, but it&#x27;s not likely going to cure cancer.

a spreadsheet, word template, mail merge, then save-as html and you&#x27;re there :)

httrack converts websites to static I&#x27;ve had good success with it.<p>It downloads the dynamic sites and converts to static pages.<p><a href="https:&#x2F;&#x2F;www.httrack.com&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;www.httrack.com&#x2F;</a>

Hmm. If I were to write my own I&#x27;d probably make a CMS rather than a SSG.

Just script it using any of your favorite tools, freemarker, jerkyl, etc..

Disagree. Just write raw HTML. It’s much much easier and gives you trivial control.<p>It’s <i>much</i> easier to write raw HTML and HTML-to-Markdown than the other way.

Not-invented-here-syndrome

I&#x27;ve never understood the point of these things. Just use a solid CMS and cache to s3 or Varnish. What&#x27;s the big deal?