Static site generators are frameworks that convert content written in markdown into HTML. Poetically, the final product of SSGs mirrors a return to the very earliest days of web development. HTML in a directory.
There are a ton of possible asterisks after that first sentence, but it's a good starting point. Markdown is just a simple syntax that is a lot faster to type out, e.g. #heading vs <h1>heading</h1>. There a buncha markdown parsers and a lot of extensions to those parsers and even mdx which can basically embed any lil JavaScript u might cook up. It can be learned by anyone in 2 mins and is not a requirement for client, designer, or even developer. But I feel a digression coming on.
They were made popular by Jekyll, the default for GitHub Pages, around 10 years ago because people had Had It with Wordpress and what a nightmare it is to configure and maintain and update and even clone initially. Computer fans turn on. And yet… everyone and their uncle wanted/wants/will want a site. 90% of the requirements follow a general shape: the désirer du TheSite wants to hand over content and a list of features, get someone to build it all and then, (crucially as t’wère) have the ability to edit and add new content in a way reminiscent to opening Word.
Not only is it easier to fulfill this request using a SSG—weeks vs months—but it also doesn’t require a WP-specialist (it’s JuSt JS after all (or Go or Ruby)) and isn’t limited by WP’s avalanche of overhead and restrictions and […] oops.
Now, here is a longish, embellished description of a typical SSG workflow. The tldr would be, client hands over content, devs convert content, add any additional features, choose a provider, use provider's integrations to handle additional stuff they don’t want to do manually, then for content mgmt the provider has plugins for hundreds of CMSs (even WP… let’s not go there) or… itself provides 😏 a CMS that client would log into to edit and add content. Many images await below to award the studious reader.
not so general overview
client sends over their content/articles—those pages and posts are converted to markdown (to then be reconverted back to HTML, stay with me)
on build, the SSG converts all those markdown documents into HTML documents (see)
it bundles, compiles, transpiles, transforms all the JS/CSS/ETAL you have and links it in the HTML
non-content pages are not restricted to being markdown, you could have a bunch of other directories that are just framework code; canonically you would have a directory like /content/blog/* with your markdown files
you choose a deployment provider, indicate a build output directory like /public, the command to do so like npm run build, then they handle the rest
they can also handle a LOT more, like postprocessing, minification, prerendering, prettifying urls, domain mgmt, https certificate mgmt, analytics, logging, lambda functions, forms, access control, firewalls, even auth for the client to log in to edit content, and wat's 2 boot is that most of em do automatically or make it so easy a non developer can configure it… (ceiling light flickers, voice becomes shriller) …NOT TO MENTION ONE CLICK BUTTON INTEGRATIONS…
(back in normal tone) for smaller less complicated sites the client is served the static HTML that is already pre-rendered on the “server” (murky concept here) and so everything loads in seconds or even milliseconds—this site for example takes 0.05ms to fire DOMContentLoaded, hundreds (thousands?) of times faster than yr basic create-react-app blog
you and the client then use a CMS to update the content—when you hit publish they make a git commit
on every commit, The Provider (actually, re evangelization, this is getting to have a tone—) will rebuild new content, cache invalidate, pre- and post-process and redeploy
they also have features like per-deploy unique urls to preview the entire site before promoting to prod
some addtl Praise (oh no) for the cache invalidation part—these sites are by nature going to be updated frequently and you can't be seeing the broken subtitle or recipe that forgot a Key Unrelated Anecdote… so they have gotten very good at this invalidation bit… so not only public, max-age=0, must-revalidate headers added to everywhere they should be, but also like global CDN edge server caches… speaking of Key Anecdotes then the recipe I promise, when cringing at a particular line in this post, I reworded and pushed updates while was it was still open on my phone (and tweaked the fonts) and in < 15s when I clicked the back button to check, I didn't even have to refresh to see the updated index and styles, and when I clicked the post, I also didn't have to refresh to see edited Pristine Post! sickening
some CMSs are barebones rich text editors with a list of posts and some are like fully featured drag and drop content-creation suites with a boatload of features that can almost stray into wix-esque land
at EOD you can switch the CMS with few if any code interventions if you were unhappy, or switch providers, or… mind explodes… the framework itself if you have mostly markdown content, speaking of which
frameworks
There is def a popular kids table in this space. Some are specific configurations of preëxisting frameworks (react, vue, next, nuxt) geared toward SSG, and others are dedicated to SSG, and built with (insert any language) or vanilla js or on, say, react, but abstract away the framework, hold on, the biggest ones are:
gatsby
react and graphql based and dedicated to SSG
built on react but when you initialize one you don't see a lot of react, just a few pithy directories
it takes 2 secs just do it npm install -g gatsby-cli; gatsby new
huge ecosystem of plugins and tools (thousands)
kinda what made me fall in love with the tech
beginner to expert
next/nuxt
for your extremely dynamic boys n girls (which turns out to be a lot of them)
react/vue frameworks respectively for server-side rendered content, but reconfigured in a SSG way
nuxt for example has a "Document Driven" config value with a Content module that reads content from /content and…
does that sound familiar ; )
i think these are maybe overkill though when TTL and TTFP are not like mission critical
they load immediately and then partially hydrate sections on the page to become interactive
a downside is that they abstract away so much that they can take some in-depth knowledge and digging when ya wanna edit ur nuxt-starter
if your client has a Netflix for Xyz idea, these will be yr best bet
Netflix literally does use Next
hugo
written in go (GASP)
has been around for a long time
extremely fast build times, good for sites with a ton content
most of them are extremely fast tho, so speed is usually not a limiting factor, and go has less devs than JS (GOSP)
so don't prematurely optimize for build speed
but also if you love go it's really fun and you should, my specific Friend to whom I sent this post
you will be quizzed on the above bullet
jekyll
how's yr ruby?
the oldest in the game and still a good option
framework used by github pages
the maturest of ecosystems, hundreds of plugins
actually almost all of these have hundreds of plugins so just assume that going forward
based on “islands architecture” (insert palm tree emoji, blazing fast fire emoji) which basically refers a strategy of changing only the necessary-to-update section of a page instead of a full re-render
immediately renders the base content then partially hydrates (insert wave emoji (these are meant to be jokes not me forgetting to add them ha ha)) these islands
wouldn’t be my first choice for a project but still fun to tinker with and a lil mind bending at first
I'm sure they will have job listings looking for 15 years Astro experience in no time
eleventy
special place in my heart as it’s super barebones and fun to hAcK oN
very little is abstracted so it demystifies any build issues
vanilla js / node
in a confusing twist has a new <is-land> component… I am getting old
According to Jamstack there are 350 more options as of Jul 24 2023 if none of these could satiate the Value Prop.
deployment providers
There a few newcomers but pretty much only three—and really only two—that make sense
aws
aws can deploy everything, but should it? a ted talk - think an s3 bucket with build artifacts… but, and I mean huge butt:
netlify & vercel
these two are much easier and nicer to deploy stuff on
it’s kind of their raison d’être
one click deploy, provisioning, git-repo-creating, templates for every major SSG framework
netlify also has benefit of having its own CMS that can added by clicking buttons and then going to the site url + /admin which will launch the CMS and reveal all yr content
they are so cool
now that I type this, I'm afraid to look at what AWS has come out with in This Space over last few years, and I elect to ignore the urge
Here are a few images of their plugin and integration sections. Both are better at certain things, but only marginally, and either works fab for anything. For the first image, there's not a whole lot more to show of netlify's plugin experience as clicking "enable" just asks, r u sure, what’s the api key, and it’s done.
But Tyler, the client wants the ability to edit content!!!!1!!1! See how the last img is a plugin of a CMS? Behold
CMS
There are currently 111 different CMS providers listed on jamstack.com which btw:
"Jamstack is an architectural approach that decouples the web experience layer from data and business logic, improving flexibility, scalability, performance, and maintainability.
Jamstack removes the need for business logic to dictate the web experience.
It enables a composable architecture for the web where custom logic and 3rd party services are consumed through APIs."
I’m going to just show some screenshots to give an idea of the range of experience a client, or a designer, or you (the dev) would have if u don’t want to work in raw markdown files. Also note that you could use WP in headless mode and integrate that with an SSG but, for the last time, let’s not go there. Any CMS can be integrated with any framework blindfolded. Without further ad—
EN SOMME
If the above, and my fervor, doesn’t make it clear what is better to choose from a time-to-build perspective, developer experience perspective, use- or reli-ability perspective, then you, reader, work for WordPress corporate xoxo.
