About this site

How this site is built — Astro on GitHub Pages, a markdown collection, a glitching title, and a few decisions that were less obvious than they look.

3 min read

This site is a static build. There is no server, no database and no CMS: pages are generated at build time by Astro and served from GitHub Pages. That constraint decides most of what follows.

The stack

Astro’s output is plain HTML, with a handful of React islands where something actually needs to be interactive. Styling is Tailwind CSS v4 through the Vite plugin, so the design tokens live in CSS rather than in a JavaScript config file. The light/dark palette is a five-hex matrix terminal: #000000, #FFFFFF, #00FF00, #002706 and #5A5A5A, with one state red for errors. The theme is applied before first paint by a small inline script — no white flash.

Deployment is a GitHub Actions workflow that runs npm ci and npm run build on every push to main, then publishes dist/ to Pages. The site lives on the szelewi.cz apex (base /) with clean trailing-slash URLs (/about/, /archives/, …), so every internal link goes through one URL helper module.

Content

Posts are markdown files in a content collection, with a zod schema for the frontmatter: title, description, date, tags, draft. The archive index, tag pages, post routes and the RSS feed all read from that one collection, so there is no second place where a post can exist — or not exist.

Drafts are filtered once, at the collection query. A draft therefore has no route, no tag page, and no feed entry. That is the whole editorial workflow, and it has not needed more.

Markdown is extended where it earns it: GFM tables and task lists, KaTeX for math, Expressive Code for code frames, plus small plugins for callouts and tab groups. The 0-features post is the reference page for all of that syntax.

The parts that are pure decoration

The name in the header and every page title glitch for about a second, now and then, in a random alphabet of punctuation. It is a CSS pseudo-element whose content is keyframed through twenty-one strings, plus a small timer that adds a class: a first hit 15–25 seconds in, then a gap of 45–90 seconds, because it should read as a damaged terminal, not as a loading state. With reduced motion enabled the timer never arms; with JavaScript off you get plain text, which is also what a screen reader sees.

The subtitle below the name is Typed.js. It waits for prefers-reduced-motion too.

This replaced an earlier WebGL build: the title was rasterised to a canvas and a wave shader ran over it, via the vfx-js library. It looked good and cost a dependency, a shader string, device-pixel-ratio bookkeeping, a document.fonts.ready gate and re-snapshotting on every resize and zoom — all of it to animate one line of text that the browser can already paint. A pseudo element, a keyframe list and one setTimeout do the same job with nothing to re-rasterise, nothing to keep in sync with the font, and no canvas in the z-index ladder.

Comments and credits

Comments are Giscus, which stores them as GitHub Discussions. The repository for this site is private and Giscus cannot read discussions from a private repo, so the discussions live in a separate public repository. Nothing loads until you scroll the comments into view.

The visual language is grafted from the wqqz.dev theme by imwqqz, used under the MIT license; the licenses for it and for the other UI dependencies are listed in the repository.

What I would change next

An OG image per post, generated at build time, and a proper project page for each pipeline. Both are content problems more than engineering ones, which is usually a good sign.

Comments