colophon

Writing

Posts are MDX in an Astro content collection, with the frontmatter checked by a schema at build time. The charts, diagrams, stats and callouts in them are Astro components from a design system I share with components.jaeaeich.com, where every one of them has a live page in both themes.

Technical terms get a dotted underline and a small card when you hover them, the way an editor shows you a symbol’s type, and clicking one goes to wherever it’s properly explained, which is often another post of mine. The definitions live in one glossary, so a term reads the same in every post, and the build fails if a post uses a term the glossary doesn’t know or a definition grows too long to be a glance.

The same source also comes out as plain Markdown at /writing/<post>.md, which the menu next to the listen button hands to ChatGPT, Claude or Perplexity if you’d rather ask about a post than read it, as an RSS feed, and as a short llms.txt for assistants. The ⌘K palette searches pages, posts, tags and every section of every post.

The listen button plays a recording made from that Markdown with a neural voice, with code, tables and figures left out, and the feed carries the recordings as enclosures so a podcast app can play them. The voice also reports when it says each word, so while a post plays a small orange dot steps along under the word being read, a hairline along the top of the window shows how far in you are, and clicking a paragraph jumps the audio there. A post is only re-recorded when the words it reads aloud change, and where there is no recording yet the browser’s own speech synthesis reads the page instead.

Figures

Figures only move when the motion says something: charts draw themselves once as they scroll into view, a chart of timings races its bars at one speed so the fastest tool visibly finishes first, a terminal session types itself out where the waiting is the point, and an architecture diagram with notes can be clicked through step by step without the page moving under you. With reduced motion, or without JavaScript, every figure is simply there in its final state.

When I post a clip of one of them, it’s recorded from the page itself in a headless browser by a small script, so the clip uses the same fonts and colours as the site instead of whatever a screen recorder caught that day.

Look

Text is IBM Plex Sans for reading and Plex Mono for labels, code and the ⌘K palette, both self-hosted. The one colour is the orange, and the dark and light themes share the same tokens so the code theme and the charts match either way. The social card for every post and list page is drawn at build time with satori and rendered to PNG with resvg, so a new post gets its card without opening a design tool.

Checks

Every push runs Biome and markdownlint, unit tests for the components, the Markdown pipeline and the palette’s ranking, and then a full build. Playwright then opens every page in both themes, on a desktop and a phone, runs axe for accessibility, checks that nothing overflows sideways, and compares screenshots against committed baselines, in the same Docker image locally and in CI so the pixels agree. After the build, a link checker walks the output so no internal link or anchor can go dead, a test reads the redirect rules so every URL I have ever shared still resolves, and Lighthouse checks that the scores haven’t slipped.

Hosting

The build is static files on Cloudflare Pages, with security headers and the old URLs’ redirects kept in two plain text files in the repo. Besides Cloudflare’s own request counts, the live site loads PostHog, which records page views and a handful of interactions, like opening ⌘K or playing a recording, without knowing who anyone is.