state of the Static Site Generator union

general overview

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, preand 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

astro

• this one is relatively new but definitively sick
• 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 Some

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, useor reli-ability perspective, then you, reader, work for WordPress corporate xoxo.