How this site works

This site is a React single-page app hosted free on GitHub Pages. Posts are markdown files committed to the repo. There is no CMS, no admin panel, and no server, with one exception I'll get to. Claude Code wrote most of the code; the architecture and the questionable decisions are mine. The stack is React 19, Vite, and Tailwind, which is to say the default stack of 2025.

writing a post

A post is a file like src/posts/2026-09-08-how-this-site-works.md with frontmatter for the title, date, slug, excerpt, and tags. Committing that file is the entire publishing workflow. The unusual part is where the markdown gets parsed: in your browser. The app pulls in every post as a raw string with Vite's import.meta.glob, splits the frontmatter with gray-matter, and renders it with marked at view time.

gray-matter is a Node library and expects Buffer to exist, so main.tsx does window.Buffer = Buffer with the npm buffer polyfill. That line looks wrong every time I scroll past it, and it stays.

Parsing client-side means the whole markdown corpus ships in the JS bundle. Right now that's nineteen posts, which is nothing. If the bundle ever gets heavy I'll move parsing to the build step, where honestly it should have been all along.

publishing while asleep

The homepage and the RSS feed hide posts dated in the future. Separately, GitHub Actions rebuilds and redeploys the site on every push, and also once a day at noon UTC on a cron. Together those two facts are the whole scheduling system: I date a post two weeks out, commit it, and on the right morning the daily rebuild picks it up and it appears. This post is the proof. It was committed in July 2026 and dated September 8. If you're reading it, the robot did its job while I did nothing.

The scheme leaks a little. The build also emits a static page per post and doesn't date-gate those, so a future post is reachable at its direct URL before the homepage admits it exists. I decided not to care. Nobody is guessing slugs to read my drafts.

static shims for crawlers

An SPA on GitHub Pages needs two hacks. The first is old news: Pages serves 404.html for unknown paths, so the build copies index.html to 404.html and deep links into client-side routes work.

The second is that crawlers don't run JavaScript. Anything that fetches a post URL for a link preview, an OG tag, or a microformat sees an empty <div id="root">. So after Vite builds, a script writes dist/blog/<slug>/index.html for every post: the built index.html with the post's real title, description, and canonical URL swapped into the meta tags. Since July it also renders the full post to HTML with marked, at build time, and injects it inside #root marked up as a microformats h-entry. A browser running JS loads React, which replaces that static content with an identical render a moment later. View source gets a real page either way, which pleases me more than it probably should.

indieweb

In July I wired the site into the IndieWeb, which for a static-ish site comes down to markup and one webhook-shaped service. An h-card on every page says who owns the domain. The site carries rel="me" links to my GitHub profile and my GitHub profile links back, and that closed loop is the identity verification other services can check mechanically. The site advertises a webmention endpoint hosted by webmention.io, so other sites can notify me when they link here, and the deploy workflow runs @remy/webmention after each push to extend the same courtesy to anything the newest post links to. Received mentions render under each post, fetched straight from the webmention.io API in the browser.

The mentions section under a post only appears once that post has actually received something. If you have a site that sends webmentions, you know what to do.

the terminal

Press backtick anywhere on the site, or click the π in the footer. You get a terminal. ls lists the posts and goto <slug> navigates to one. ping measures real fetch round-trips to the site. boot runs a BIOS sequence for DZOBA OS, an operating system that does not exist. clouds is an ASCII cloud animation. guess is a number guessing game.

board is the interesting one: an anonymous message board, and the one place the "no server" claim breaks. Messages go to Firestore, the site's single piece of backend, and your IP is partially masked before anything displays it. The Firestore free tier at this site's traffic level rounds to zero dollars.

help doesn't list quite everything.

the bill

GitHub Pages hosting, Actions builds, Firestore, and webmention.io all cost nothing at this scale, so the recurring cost of the site is the domain renewal. The build takes under a second on my laptop. It's hard to justify more infrastructure than that for a blog with a fake BIOS.