As a Software Developer, I find the Jamstack approach very appealing, especially for blogging. With static content served over a CDN, your site is served fast and with no server to manage, avoiding a big security challenge. Backups are a non-issue as you typically keep content on GitHub or similar, separate from any theming elements. For any Static Site Generator (SSG), there are tons of “themes” available, so all you need to do is to point the theme to your content files and a fully rendered blog is ready to be served over any of the CDNs (Netlify, Cloudflare and so on). If you need additional services like site-wide search, analytics, a commenting system, you can either self-host these services or go for hosted/managed version of these.
The issue is that there are too many pain-points you must go through to go from your markdown (and images) files on GitHub to a spanking blog.
“Themes” are more complex than you think
Maintaining and extending them to fit your needs take a lot of your time and energy. As a Software Developer I expect following from a theme:
- Server-side math rendering: so you don’t have to push katex.js to 1000s of visitors.
- Server-side code highlighting: some themes still push highlight.js to clients.
- Social Discovery tags so your blog post links look decent when shared in social media and help search engines.
- schema.org microdata for Google
- Open Graph Protocol (OGP) tags for Facebook
- Twitter Cards
- “See Also …": suggest other posts on topic(s) covered in the current post.
- Navigation based on tags
- Proper pagination
- Asset optimization
- Minify JS and CSS
- Image optimization
- Responsive design
- RSS feed
Additionally, themes typically come with complex bundler (like Webpack) and automation tool (like Gulp) configuration. Maintaining or extending them is a task in and of itself.
Finally, themes are not professionally supported in general. The ultimate burden is on you to maintain and extend it to achieve everything listed above (and more), which comprises a “theme”.
Built-in site-wide search
Apart from embedding a Google domain search widget, there is no easy way to integrate a proper blog-wide search experience (please don’t push JSON encoded index to clients).
A decent commenting system
Setting up a commenting system is hard unless you go with some third-party solution. Blogosphere is filled with hacks to make it work with a “static site”:
- Using Netlify Forms for visitor comments -> Netlify function process and queue form responses -> Slack notifications to approve/disapprove -> Trigger re-render of website.
- Use GitHub pull requests for comments using Staticman. Pain to setup.
- Use GitHub issue: create an issue corresponding to each blog post and redirect visitors there to make a comment. Periodically re-render blog to pull in and render these comments (issues) inline.
So much for blog comments in 2021.
Privacy preserving analytics
Free solutions like Google Analytics are blocked by many, it injects too much JS and it tracks too much. Privacy friendly analytics like Plausible are good but when a hosted commenting system and analytics costs more than rest of your setup, it feels wrong.
Selecting an SSG
300+ SSGs (Static Site Generator) exist but which one to pick? Picking the right SSG is important. For example, a popular SSG Hugo has serious problems with math blocks (GitHub issue, closed because of “trolling”). It provides no uncomplicated way to ignore content within math blocks which requires you to carefully escape characters like
\ in your equations. This is a problem in large, convoluted Latex expressions. You discover such problems only after you have burned several days tweaking your theme (or writing one from scratch) and posting a bunch of content.
Another popular SSG Gatsby can end up requiring so much legwork, combined with its own bugs, that you will yearn to go back to writing in plain HTML.
My goal is not to look down on these OSS projects (I understand how demanding it is to develop and maintain these) but to highlight how much friction an already busy developer experiences despite the existence of these elaborate tools.
What you see in VSCode Markdown preview is not exactly how your content will render on your blog. Different SSGs, different Markdown implementations, different “shortcodes”, different outcomes.
In its current state, Jamstack approach puts a significant burden on an individual trying to put out a blog. Features like in-site search, a decent commenting system, reliable and privacy-focused analytics are left to third party providers or complex self-hosted setups. Editing experience is subpar too as editors like VSCode do not understand SSG specific markdown extensions.
An ideal solution would be where I can just point a blogging platform to my content (markdown and images) and it delivers all of what I described above. This seems far from the current state-of-the-art in the Jamstack world.