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's way easier to get this workflow dialed in when you're doing things locally since the switching cost between solutions is that much lower.
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.
If you don't write one, the chance is good, your blog would stay empty.
In all seriousness does everyone and their mom write a static site generator? I did because its fun and easy. Off the shelf ones can be cumbersome and not work quite how I want them to.
So am I. My first one was written in C in 1995, and the resultant site run under NCSA Httpd. DIY-ing becomes tedious after several cycles, though.
On the other hand, my experience with generally available SSGs has been miserable. They keep breaking my site after a few upgrades. At this point, I am very close to just spinning up wordpress for a new site.
I admin a local org's WP site, because someone has to, and thoroughly appreciate the SSG that I use personally.
I’m well aware of the irony of building yet another SSG to help people avoid doing the same. But I’m addicted to building SSGs—this one was my fifth, and I’m considering making another one (insert facepalm here).
Surely you can learn a lot in the process, but how much time does it need?
It was probably the author's fault to select NextJs for it. Maybe something simpler like gohugo might have been better: the tool is just a binary file, that doesn't require extra dependencies.
Where static site generators shine are websites that are not blogs. Especially when generated from a data source. Then you can tailor your ssg to the data source, update the data and run the generator to update the site.
I certainly learned to keep the featureset of such a program to a minimum in order to have a chance to "complete" and publish it.
Btw. the article lists five points that really come close to how such a generator may work. I think mine only leaves out the CSS compilation stuff and offloads the Markdown processing to pandoc...
Then I discovered that for my writing style, org-mode with embedded scripts and plotting code really just works. I don't have to think much and I can focus on just writing. That particular authoring/publishing tool never gets in the way of what I want to express.
So I ended up patching over parts of org-mode to make it my static site generator. Sometimes the best is somewhere in between the extremes.
It'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.
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.
Alternately, for many, there's more value to themself and everyone else if they grind on those technical skills rather than distract themselves with a hobby they seem inclined to put off.
If you really want to write, you'll write. If you really want to hack, you'll hack.
A lot of people think they should write, but actually just want to hack. And that's not a problem! The image of writing provides some orientation to the hacking, but it's the hacking itself that can be most fun and enriching for them.
Do the hacking, and if you never get around to the writing, don't sweat it. If you're honest with yourself: it was never really about that, was it?
This project isn't about blogging, you need to look at it from a side project pov.
I think this is a common misconception, that these people want to write a blog post but are failing or procrastinating when they don't have to. When in reality, these people are developers and makers who look at their personal website from tech community's "little corner on the internet" pov.
They feel frustrated with the solution and feel they can develop better-tailored one for themselves. Putting out blog posts isn't a priority or a concern for most of these developers. They're passionate about their tools. They make tons of side projects. They're not wasting time. They don't necessarily have a more important post to write about.
If you're looking at it from a blogger/writer's perspective, sure that's wasteful, but, again, that's not what this is about.
Yep. You also see this often in small companies/statups that would write their own ticket systems and internal administrative intranets before they even had a product.
If you write about tech and your site doesn’t load instantly why should anyone read your words since you obviously don’t care
I guess that's what a framework is about. You get some abstractions that make your life easier and you pay by buying into the concepts.
> [...] 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.
If the current version is doing its job, why update? It's a SSG not a browser that connects to the internet.
So I disagree. I'll not write my own and keep the existing one as long it's not too much hassle.
Because it's a hassle and you'll be left behind when you need a new dependency or there's a feature you like. By then, you have years of updates behind including depreciations, conflicts, etc. It might turn to a full-blown migration. All that is much easier if you update along.
Both the code and the text data were in the one file.
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.
Over time, the code changed a little, such as to convert from HTML tables to CSS with the same look.
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.
(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 "/" (or leaf-fname "index.html"))
(web5-page-html title-list
(web5-format-sideheads title-list
sections))))
And also various others, for various reasons. The thing about static site generators is that they are fantastically easy.
I wrote a static site generator once. I used a Makefile and m4 macros!
Yes, it's true: nobody could stop me. It's much more debatable whether the "you should" 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's machine.
It worked. For some reason, the person who took over the site after me did not follow in my footsteps and keep using m4.
Shame...
Anyway, my first and only SSG was based on Atom for storage, PHP for backend and XSL for client side rendering.
We called this flat file CMS which was the style at the time and...
I'd say this person "gets it". We spend waaay too much time bickering about what people "should" do, in my opinion.
So I wound up storing the basic metadata in a JSON file, then I assemble the header and footer of the page with PHP, which is then rendered out to a complete HTML page.
It's not quite a SSG, but just a little help automating the boring stuff.
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've put 1.5 years into this (added my own k8s hosting on GCP too - also with its issues)!
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.
It's crazy I spent so long on the Saas version and didn't get to a working website, and with the command line version now have a couple sites up!
It's a cool experience to make your own site builder, definitely learn something each time you do.
Here are the sites I made:
https://www.madebyhelena.com https://LouisSayers.com
(Helena is my partner, I remade her site which she had created on a different platform)
Metalsmith (Node/JS): https://metalsmith.io/
Haunt (Guile Scheme): https://dthompson.us/projects/haunt.html
I’m sure there are many more.
My own SSG is Django+Distill.
I had used pelican before; but I wanted to get a better handle on using Markdown and Jinja libraries "from the other side" 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.
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 "debug" feature to dump everything available to a template is nice.
I haven't bothered with RSS or sitemap yet, but i did do a nice calendar view render of my archive indexes; which i don't think could've been easily wedged into pelican's notion of how sites work. https://snafuhall.com/news.html
I also host my book-draft on my site. I initially tried to get Pelican to do it, or to write something that publishes to Pelican, but it just didn't work. I ended up writing a hundred lines of fairly simply python to do the same job.
Now I'm on the verge to write my own generator again (probably in Kotlin or in Rust), because I'm tired of Hugo's breaking changes and because I still don't like the ugly Go templates.
You can run Java from 1.1 on modern JREs. PHP from the early 2000s can still work. It all depends on what your stack looks like. If you're using the highly unstable "everything moves fast and constantly breaks" newer stuff, then sure. It's hard to see Python 3 breaking within the next 5-10 years, after how well the 2->3 changes were received.
I'd wager though even with newer languages, if you wrote something in Go, Rust, Kotlin, etc. today, it will still function in a decade.
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!
Back in the day we didn't have SSG's. We just wrote the html/js/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't fancy (or pretty) but it was simple and it worked.
I do not care about how "fun" it is to maintain, I care if people can get the information they need. It should take as little effort as possible, because extra effort maintaining the site has to be taken from something more valuable I could do with my time.
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.
Its better to figure out which of the existing SSG'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.
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 don'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.
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 "putter around in the workshop"
Nothing wrong with using someone else's, but really, you should write your own.
I've used a static site generator myself to host a blog, and I've been pretty happy with it, yet I've never felt the need to write one myself even for a single second.
I've written a ton of little SSGs over the years, and every iteration I've learned what kind of features I really need, and which I don't.
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's written in Ruby using the Kramdown markdown gem, and pretty much nothing else outside the stdlib. It works perfectly for me, and that'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).
I'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'll be used by anyone else. I think too often developers these days get caught up in trying to make their project be "the next big thing" in whatever domain it serves, but honestly sometimes it's nice to just write something for yourself :)
This was about 20 years ago now. Once it a while I consider refactoring/resurrecting it. But I've not found the time.
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'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'd do. Just stitch them together, instead of trying to get my first-steps into someone else's static site gen.
* I wanted one that has lots 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
The result being perfectly static means its perfectly fast. It also means there's a lot of crude overlap - every page has the same HTML copied and pasted a million times. But that's OK, it's small, so it's still faster.
There's no requirement for websites to be generated either statically or dynamically. The best websites are just files in folders.
<p>whatever stuff here...lorem ispum, etc...</p>
<!--# include file="/menu.html" -->
<p>etc etc</p>
Five years ago I dove into using an ultra-light-weight framework called MetalsmithJS. It's super minimal, but does what you need. I'd spent 10 years using the Drupal monolith, and did not regret the move. Yet it's open-source community dried up, but mostly because the framework does what it claims and then stopped expanding!
Here's a blog post... https://doublejosh.com/post/186193119278/metalsmithjs-is-sti...
Then two years ago I needed a more robust SSR system based on React, so I went with GatsbyJS. It'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.
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't mean better.
I'm keen to try other simple frameworks when the result is a static site. I may give https://www.11ty.dev a shot.
We went with Gatsby for our overhaul and honestly, not looking back unless forced to. I realize it doesn't scale all that well but we're at ~10,000 pages and our build time is about 8 minutes without a lot of optimization. Given our refresh interval is 15 minutes, nothing to worry about from my perspective.
People keep chattering that NextJS might suit our needs better but GatsbyJS sure ain't broke.
I setup a cronjob to fetch weather data and run the SSG to parse the XML and render a weather "website" on my VPS.
But for the blogs I've had/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)
It's really not that rosy tbf. I went through something like: SvelteKit, 11ty, Astro, Zola, hugo, and possibly others in-between.
It's pretty easy to develop a preference where none of the mainstream SSGs fare well at. Some established large SSGs might do X but they have their own challenges too.
You start migrating by filtering based on some criteria, and find a match that does a great job initially, only to get bitten later, when you've migrated and settled and start seeing the cracks.
For example, Zola, and many others, doesn't support asciidoc. The handful that do have their own problems too. (I'm now with hugo which support asciidoc but I'm still determined to build my own ssg)
It's not fantasizing about the perfect tool, as much as developing a setup where you're comfortable and happy. Especially in the case of SSG, where you're more exposed to the internals and by extension any errors/problems.
Similarly hard to find is tagging posts based on file system metadata (e.g. everything in “posts/linux/“ should be tagged with “linux”).
It needed a specific XSLT processor as most couldn't generate individual files, but it was nice that it worked with off the shelf software, so technically I didn't write a single line of code.
(XSLT is madness, don't attempt)
XSL did eventually add multiple outputs, but yeah: do not attempt :)
I have a lot of websites (maybe more than 20) and they're a mix of old version of next.js, hand rolled websites and some solid.js websites.
The solid.js sites are fairly easy to update - but it's also very new (the oldest being 3 years) and I'm not sure it will stay that way forever. You just need one wrong decision from the fun guys at ECMA and frankly I've been burned already by commonjs vs esm.
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'm using not having a fixed node version, but I've also found some dependencies breaking compat from one patch to another.
I guess the key takeaway is: use as little deps as possible.
- It's fun
- It improves with each iteration due to experience gained
- It's great to have a sample project to create in any language you consider using as it's a small yet realistic way to discover how that language works and what the ecosystem provides
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've written my own Markdown parser and am working on my own templating engine (bit like Razor, ERB, or PHP).
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.
It also means a very simple, very fast server that runs forever without maintenance. You don't need much to serve static files.
Above all, it means source-controlled content and content branches. This is great for big changes that span multiple pages.
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.
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.
Then I started a little library for replacing Maud, for a better developer experience [2] (still looking for a better name).
The important thing for me is having fun in the process, my personal website is a sandbox for playing and experimenting :)
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: https://github.com/captn3m0/news
Another place where it made sense to use SQLite as a data source, I wrote a Jekyll SQLite plugin.
I find my lingering desire to roll out an SSG slowly fading.
Found this post comparing them & more, Eleventy (man that's annoying to type on mobile with autocorrect though!) for speed it says. https://mtm.dev/static
I'm really attracted to the Eleventy approach on the whole - there's no bloat, they don't inject any of their own js, I can move fast and only add complexity where I actually need it.
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
The SSR isn't to avoid HTML, it's for template purposes.
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.
No compilation step needed.
It downloads the dynamic sites and converts to static pages.
It’s much easier to write raw HTML and HTML-to-Markdown than the other way.
Of course, that doesn't mean I need to write my own. I just used a simpler SSG. In my case Jekyll.
I don't need to set up S3, Varnish, a server, a database, making sure my server + cms is up to date. It costs me $0, it's on a cdn and it's lightning fast + no headache. What's not to like?
When I had a dynamic blog (DB backend, etc), I got hacked because I wasn't updating the SW often. Not having to worry about things like that is a significant quality of life difference. I want to run my life, not have my tools run them.
But frankly, let's invert the question. What exactly is the benefit of using a CMS vs an SSG like Pelican? After having used the latter for over a decade, it's dead simple. Open a file. Write your content. Run make. And publish. It's trivial to back up. I don't have to know what a cache is. I don't have to keep updating SW. What is the actual benefit of a CMS for a single user like me?
Aside from that, a CMS is overkill for something like a simple blog. I might consider one for a more complex site but for a blog there’s no need.
Even though you can make a CMS fast, with a static site you can forget about performance altogether.
Finally, it meshes very nicely with editing files in eg markdown locally, which for some people (like me who live in Neovim) is a much nicer experience than editing things in a webpage.
It uses Git and Markdown for easy deployments to your serverless CI/CD pipeline just as you described.
I'd love your feedback :)
If you use a CMS, it has to run somewhere. If you don’t want it on a server, you probably don’t have the same config on your dev machine. Most CMS require you to configure root domain paths etc. and they are different on your local machine. It’s all a lot more complicated than using an SSG to transpile a bunch of markdown files to HTML on a dev machine and upload them.