The Surprisingly High Table Stakes of Modern Blogs

Bottom Line Up Front: You are probably underestimating how much goes into blogging technology these days.

note: i have rolled up most of these opinions into my own swyxkit starter template.

Reader Experience

• Article header and body
  • Good typography
  • Readable, accessible, branded styling
  • Embedding rich media (particularly YouTube and Twitter embeds, but also Repl/Sandbox embeds - mind the mobile view)
  • Footnotes (a really great way to add extra context without bloating main text)
  • Truncation marker for pagination
  • Content Transclusion
  • Syntax highlighting of Code (main players: Prismjs, Highlightjs, Shikijs - preferred if static - no css/js embed needed)
    • including git diff displays - I had trouble with this recently
    • make sure to test overflow code blocks - in general try to implement defensive CSS
  • render as popover on desktop, as footnote on mobile/email?
• Metadata
  • Table of Contents extraction/display/highlighting/collapsing
  • Reading time estimation (debatable)
  • Reader Comments (Disqus? Utterances?) and Webmentions
    • Sanitizing/moderating comments?
  • Social Proof
    • Reader highlights (like Medium does)
    • Claps/likes/etc
    • Meta conversations on HN/Reddit/Twitter/etc
• Theming
  • Dark/Light mode toggles - avoid dark-mode FOUC!
  • Custom theming (see Max Bock site)
• Blog Index Browsing features
  • Search: Simple filters, fuzzy matches, faceted search
  • Tags and Categories. Tag hierarchies?
  • nprogress loading indicator
  • Autolink headers
  • Pagination - for posts, for tags (example)
  • Archive (unpaginated) (example)
  • Recommendations:
    • Next/previous buttons
    • “Related” reads
    • “You may also like” recommendations
  • 404 page - try to guess what the user wanted
• Accessibility
  • Using semantic HTML with proper Heading hierarchy
  • SVG Icons
  • Tap targets
• Security
  • X-Content-Type
  • X-Frame-Options
  • X-XSS-Protection
  • CSP
  • auto add target="_blank" or rel="noopener" to links

And everything should look great on mobile devices and (at least not horrible on) ultrawide monitors.

Web performance is of course a huge part of the reading experience but I’ve put it in the section below for even spacing reasons.

Author Experience

• WYSIWYG writing (with keyboard shortcuts) - use a CMS? Roll your own? Markdown vs Blocks?
• If writing in static markdown files, the ability to colocate static files (eg pdfs) next to the file (instead of dumped in a big fat “files” folder with no clue which post it belongs to), and to easily write relative links to them in the markdown that will be transformed to the write path
• Customizable metadata (with good inference when not supplied)
  • slug
  • publish date
  • edited at date
  • canonical url
  • description
  • og:image
  • layout
• Shortcodes/Unfurls
• Image uploads - best workflow is to paste the image from clipboard right into the textbox and have it upload, as Github Issues does.
• Static data entry
  • eg to log talk and podcast appearances
• Analytics
  • Server side analytics (Netlify Analytics)
  • Google Analytics
  • Privacy preserving clientside analytics (eg Fathom)
• Mobile authoring/editing experience

Distribution/Reach

• OpenGraph tags - these will determine unfurls.
• Autogenerated og:image off a template? on request or at build time? Your title/description/og:image will be read by more people than your post itself
• Is a sitemap needed these days?
• Favicons + Webmanifest
• Redirects for moved/broken links
  • outbound: broken link checkers
  • inbound: redirect checkers
• RSS feed: even better - customizable RSS feed by topic
• This is HUGE for reaching loyal readers: Newsletter publishing on a per-post or weekly-digest basis. IMO this is the big win of Substack, the only platform really taking this seriously
• AMP support? debatable
• Web Performance (affects Google ranking so I put it here)
  • Mind your lighthouse scores
    • Lazy load images <img loading="lazy" />
    • Image optimization
    • try to set image aspect ratios for cumulative layout shift
  • Find “lite” versions of all third party scripts
    • https://github.com/paulirish/lite-youtube-embed
    • Youtube embed: React: https://static-tweet.vercel.app/ , Svelte
    • https://github.com/lukeed/ganalytics
    • or put them in partytown https://github.com/BuilderIO/partytown
  • CDN caching/serving from Edge workers (Cloudflare, Deno, Fly)
  • PWA/Offline caching (example)
  • Resource hints/preconnects

Developer Experience

• Plugin systems for adding every feature above in <10 lines of code (example)
• Build times should be <1 minute
• Type safety for data schemas
• Fast content preview (preferably without having to run a local server)
• Monitoring/alerting - when your site goes down or a single popular page disappears for whatever reason, who finds out first? your readers or you?

This is often tied with the debate about whether or not the blog should be Jamstack - mostly statically generated and hosted on a CDN, or traditionally mostly generated on request and cached for some amount of time.

Misc

• Portability to other platforms in future
• Popovers and link previews per Andy Matuschak
• i18n/translations

Context

It is often said that one of the best ways of learning a new language, from Ruby to Rust, is to implement a static site generator (fun fact - it was actually my take-home interview for Netlify!). Depending on the requirements, it forces you to learn everything from filesystem access, making network requests, parallelizing code, parsing configs, using libraries, creating plugin systems, injecting javascript, writing a CLI, and deployment.

Because there are accordingly so many static site generators, most people tend to devalue them, in the “I could build this in a weekend” sort of way, and end up building their own blogging platforms every few years as a way to “stay sharp”. But that’s a very 90’s view of blogging technology - and the requirements of a modern Blog has diverged a lot from the basics of static site generation in the past 30 years. In the end, your readers have a poorer experience and your blog may not get the reach it might deserve.

I of course am no exception to this, being maintainer of my own small blog template for the Svelte ecosystem. I am intimately familiar with the modern dev blogging platforms like Dev.to and Hashnode, and these days spend plenty of time reading the many Data Engineering Substacks, and only appreciated how much they do for us that you should not handroll (or should consider building if DIY, because it is genuinely such a good feature).

This is an appreciation I only arrived at after ~5 years of constant blogging, so I figured I should write down what I see as “table stakes”, for you to appreciate when considering your next great blogging platform, without trying to sell you any particular solution.

For what its worth, I do think most people, even developers, should not handroll their own blogs and should try to use Devto/Hashnode/Substack (Wordpress is of course an option) accordingly, because most people get so caught up in being PM + Dev for their handrolled blogging software that they never get to the writing. Try to do, say, 20 straight weeks of regular blogging, to prove that you are actually going to be a blogger, before you spend a bunch of time coding up blog software you end up not using.

The most important feature of a blog is its content - if you write good content, people will overcome almost any hurdle to come and read it. Don’t forget that.