Danny Smith - Articles

How my personal video platform works

Fri, 24 Jul 2026 00:00:00 GMT

My introduction to LoomClone was pretty sparse on technical detail so I’m gonna dive into a bit of that here, specifically how the mac app and backend API work together for the lifecycle of a recording. You should go read the intro if you haven’t already or this won’t make much sense.

I think the best way to explain this is to walk through the lifecycle of a recording one step at a time.

1. Opening the menubar app

When I open the menubar popover we start some lightweight preview sessions for the selected camera and audio devices and start capturing screenshots of the active display to provide a preview for that. We also begin polling for new devices to keep the dropdowns up-to-date and check the server is reachable and the local data directory is writable. All this is intentionally separate from the actual capture sessions and is torn down once the menubar popover is closed. Its only purpose is to confirm to the user that the chosen sources are set up properly and let them choose a few settings.

2. Pressing record

The recording toolbar shows a short countdown while in the background:

We immediately start capture sessions for the selected devices so they have time to warm up, check the audio source is actually providing samples and spin up the various writer sessions so they’re warm. We also double-check a few other bits about the video and audio streams we’re getting.
We hit the server to generate a UUID and unique three-word slug for the video. This creates a new recording in the database and seeds a data directory on the server, returning the UUID and slug to the mac app.
We use the UUID to create a local data directory and seed it with an init.mp4 to act as an entrypoint for the local m4s segments.

When the countdown finishes we initiate an internal metronome to help keep things in sync and begin the writer processes.

3. During Recording

We use two capture sessions: one for the screen and another for the camera+audio together (or just the audio if there’s no camera feed). These feed an orchestrator which maintains a metronome & recording clock, handles user pausing/unpausing by pausing the clock, and deals with things like frame caching.

There’s a ton of fiddly stuff in here to gracefully handle video sources which deliver frames unpredictably. Every video frame and audio sample is timestamped using the hardware capture time it arrived with rather than the wall clock, so variable latency between capture and reaching my code is irrelevant for timing sync. When camera & mic are both selected they share a single capture session so are inherently aligned to sub-millisecond accuracy. While the metronome ticks along at the target frame rate, it’s just a budget: on each tick we emit whatever the source has actually delivered. So a camera that can only manage 24fps produces 24fps output rather than the horrible corrupted mess I ended up with from my initial metronome implementation.

Anyway….

During recording we continuously write three media files to disk locally, directly from the capture sessions:

screen.mov - The “raw” output of the ProRes screen capture session.
camera.mp4 - The “raw” output of the H.264 camera capture session, ignoring any user adjustments to white balance & brightness, including an audio track.
audio.m4a - The “raw” audio from the mic.

These are never sent to the server, but having them locally means I can always pull them into Final Cut Pro if I decide to do some proper editing later, and have a reliable backup if composition fails for some reason. We also keep a timeline of events in memory and continuously write to a few log and diagnostic files.

The video we send to the server is composited from the capture streams using the upload resolution and framerate selected by the user before recording. Camera adjustments for white balance & brightness are applied to the camera feed and both it and the screen feed are downscaled and/or cropped to an appropriate size & aspect ratio, taking into account the chosen stream quality.

👉

User Actions While Recording

The following user actions affect the composited recording.

Pressing pause in the toolbar temporarily pauses all writers until unpause is pressed, along with the metronome.
Pressing chapter marker in the toolbar adds an anonymous marker to the recording timeline which can later be edited in the admin app to create viewer-facing chapter markers. If pressed while paused it’s added at the next unpause timestamp.
Switching mode in the toolbar causes the composited recording to swap to the relevant feed (screen or camera). In screen & camera mode the camera feed is rendered as a small circular overlay in a corner of the screen.
Moving the camera preview from one quadrant to another (eg. bottom-right to top-left) moves it to that corner in the composited output (when in screen & camera mode).

As the composited video is generated it’s encoded at an appropriate bitrate and written to disk locally as a series of ~4 second .m4s segments before being “streamed” to the server via a queue of simple PUT requests. Failed puts are retried indefinitely with an exponential backoff (and we stop bothering entirely while the network is obviously down), but they’re all sent via a queue so even a ~10 min connection loss just means the queued segments are sent up on reconnection. These PUTs are idempotent on the server.

There are a couple of other resilience details worth a mention. If the Metal compositor hangs or returns a bad frame – which can happen under sustained GPU pressure – we detect it, rebuild the context and carry on. And when the screen content isn’t changing for a while (eg. I’m showing a static slide while talking to camera) we emit synthetic keep-alive frames so the HLS segments never go empty and break the playlist.

We also keep an eye on the capture sources themselves: if the screen, camera or mic stalls or drops out mid-recording a warning pill pops up in the toolbar so I know something’s wrong. And if the camera in a shared camera+mic capture session dies we fail over to a separate, always-running mic capture session so the audio at least keeps recording.

The recording timeline is periodically written to a temporary file on disk to facilitate recovery if anything goes wrong.

4. Pressing Stop

When we hit stop, the capture sessions and writer processes finish and if the UploadActor queue isn’t empty it’s given up to ten seconds to finish uploading before remaining segments are marked failed locally¹.

The recording timeline is used to write a local recording.json to disk which includes:

Basic info like UUID, start/end timestamps, duration etc.
Details of the input sources and raw writers used, including hardware details and the like.
Details of the writer used for the composited video including the encoder and streaming settings.

It includes a timeline of events during recording, each of which has:

kind - type of event (eg segment.uploaded or modeChange.CamOnly).
t - time of event as seconds since metronome T0.
wallClock - datetime of event per OS clock as UTC.
data - Other useful stuff as an object. This depends on the kind of event.

While the event timeline includes segment-related events, recording.json also contains a separate list of the generated segments, including:

bytes - size of the segment
durationSeconds - segment duration
emittedAt - Metronome time the segment was emitted.
filename - Filename on local filesystem (eg seg_000.m4s).
index - Order of segments chronologically as emitted by the compositor. We can use this to deal with any ordering issues later.
uploaded - True if any PUT for the segment returned OK, false if not.

This data is written to a local recording.json and then POSTed to /:uuid/complete on the server to tell it we’re done recording.

Example recording.json

Here’s an example (with a bunch of the repetitive data removed).

{
  "app" : {
    "build" : "1",
    "osVersion" : "26.5.1",
    "version" : "0.1.0"
  },
  "encoder" : {
    "audioBitrate" : 128000,
    "audioCodec" : "aac-lc",
    "outputHeight" : 1080,
    "outputWidth" : 1920,
    "segmentIntervalSeconds" : 4,
    "targetFPS" : 30,
    "videoBitrate" : 8000000,
    "videoCodec" : "h264",
    "videoProfile" : "High"
  },
  "events" : [
    {
      "data" : {
        "file" : "screen.mov"
      },
      "kind" : "raw.writer.started",
      "t" : 0,
      "wallClock" : "2026-06-06T16:47:20.381Z"
    },
    {
      "data" : {
        "file" : "audio.m4a"
      },
      "kind" : "raw.writer.started",
      "t" : 0,
      "wallClock" : "2026-06-06T16:47:20.381Z"
    },
    {
      "kind" : "recording.committed",
      "t" : 0,
      "wallClock" : "2026-06-06T16:47:23.223Z"
    },
    {
      "data" : {
        "file" : "camera.mp4"
      },
      "kind" : "raw.writer.started",
      "t" : 0.004191994667053223,
      "wallClock" : "2026-06-06T16:47:23.227Z"
    },
    {
      "data" : {
        "bytes" : 4229782,
        "durationSeconds" : 4,
        "filename" : "seg_000.m4s"
      },
      "kind" : "segment.emitted",
      "t" : 4.875511791,
      "wallClock" : "2026-06-06T16:47:28.056Z"
    },
    {
      "data" : {
        "filename": "seg_000.m4s"
      },
      "kind" : "segment.uploaded",
      "t" : 4.891072416,
      "wallClock" : "2026-06-06T16:47:28.071Z"
    },
    {
      "data" : {
        "from" : "bottomRight",
        "to" : "bottomLeft"
      },
      "kind" : "pip.position.changed",
      "t" : 36.89907425,
      "wallClock" : "2026-06-06T16:48:00.079Z"
    },
    {
      "data" : {
        "from" : "screenAndCamera",
        "to" : "cameraOnly"
      },
      "kind" : "mode.switched",
      "t" : 41.911716833,
      "wallClock" : "2026-06-06T16:48:05.091Z"
    },
    // ...
    {
      "data" : {
        "branch" : "pop",
        "deltaMs" : 1989.68825
      },
      "kind" : "monotonicity.rejected",
      "t" : 44.876459916,
      "wallClock" : "2026-06-06T16:48:08.056Z"
    },
    {
      "data" : {
        "staleDurationSeconds" : 1.016079208
      },
      "kind" : "keepalive.emitted",
      "t" : 56.630524583,
      "wallClock" : "2026-06-06T16:48:19.810Z"
    },
    {
      "data" : {
        "from" : "cameraOnly",
        "to" : "screenAndCamera"
      },
      "kind" : "mode.switched",
      "t" : 56.944255875,
      "wallClock" : "2026-06-06T16:48:20.124Z"
    },
    {
      "kind" : "recording.stopped",
      "t" : 159.799141458,
      "wallClock" : "2026-06-06T16:50:02.977Z"
    },
    {
      "data" : {
        "code" : -11800,
        "domain" : "AVFoundationErrorDomain",
        "error" : "The operation could not be completed",
        "file" : "camera.mp4",
        "underlyingCode" : -16364,
        "underlyingDomain" : "NSOSStatusErrorDomain",
        "underlyingError" : "The operation couldn’t be completed. (OSStatus error -16364.)"
      },
      "kind" : "raw.writer.failed",
      "t" : 159.799141458,
      "wallClock" : "2026-06-06T16:50:03.238Z"
    },
    {
      "data" : {
        "message" : "diagnostics: iters=7450 emit=3891 skipStale=2703 keepAlive=11 mono=53 neg=7 noSrc=785 peek=0 pop=623 camFrames=3350 (~0.00fps) scrFrames=4721 evictions=2399 compFails=0 dropRate=0.8%"
      },
      "kind" : "error",
      "t" : 160.061301666,
      "wallClock" : "2026-06-06T16:50:03.239Z"
    }
  ],
  "hardware" : {
    "arch" : "arm64",
    "model" : "Mac14,9"
  },
  "inputs" : {
    "camera" : {
      "advertisedFormats" : [
        {
          "height" : 720,
          "maxFrameRate" : 30.00003000003,
          "minFrameRate" : 30.00003000003,
          "pixelFormat" : "420v",
          "width" : 1280
        }
      ],
      "name" : "ZV-1",
      "selectedFormat" : {
        "activeMaxFrameDurationSeconds" : 0.03333330000003333,
        "activeMinFrameDurationSeconds" : 0.03333330000003333,
        "didLockRate" : true,
        "height" : 720,
        "pixelFormat" : "420v",
        "width" : 1280
      },
      "uniqueID" : "0x2111100054c0de4"
    },
    "display" : {
      "height" : 1080,
      "id" : 3,
      "width" : 1920
    },
    "microphone" : {
      "halInputLatencyMs" : 13.75,
      "name" : "Yeti Stereo Microphone",
      "uniqueID" : "AppleUSBAudioEngine:Blue Microphones:Yeti Stereo Microphone:ReV8:2"
    }
  },
  "preset" : {
    "bitrate" : 8000000,
    "height" : 1080,
    "id" : "1080p",
    "label" : "1080p",
    "width" : 1920
  },
  "rawStreams" : {
    "audio" : {
      "audioCodec" : "aac-lc",
      "bitrate" : 192000,
      "bytes" : 3134595,
      "channels" : 2,
      "filename" : "audio.m4a",
      "sampleRate" : 48000
    },
    "camera" : {
      "bitrate" : 12000000,
      "bytes" : 11308795,
      "failed" : true,
      "filename" : "camera.mp4",
      "height" : 720,
      "videoCodec" : "h264",
      "width" : 1280
    },
    "screen" : {
      "bitrate" : 146343794,
      "bytes" : 2923201587,
      "filename" : "screen.mov",
      "height" : 2160,
      "videoCodec" : "prores422proxy",
      "width" : 3840
    }
  },
  "runtime" : {
    "cameraIntervalP50Ms" : 35,
    "cameraIntervalP95Ms" : 67,
    "effectiveCameraFps" : 20.96381726106132,
    "effectiveScreenFps" : 29.5433376983494,
    "metronome" : {
      "emitOK" : 3891,
      "iterations" : 7450,
      "keepAliveEmits" : 11,
      "monoRejects" : 53,
      "skipsStale" : 2703
    },
    "outputFps" : 24.41815371721232,
    "screenIntervalP50Ms" : 35,
    "screenIntervalP95Ms" : 67
  },
  "schemaVersion" : 3,
  "segments" : [
    {
      "bytes" : 4229782,
      "durationSeconds" : 4,
      "emittedAt" : 4.875511791,
      "filename" : "seg_000.m4s",
      "index" : 1,
      "uploaded" : true
    },
    {
      "bytes" : 4136495,
      "durationSeconds" : 4,
      "emittedAt" : 9.318954291,
      "filename" : "seg_001.m4s",
      "index" : 2,
      "uploaded" : true
    },
    // ...
    {
      "bytes" : 1427814,
      "durationSeconds" : 3.0933333333333333,
      "emittedAt" : 159.956935541,
      "filename" : "seg_039.m4s",
      "index" : 40,
      "uploaded" : true
    }
  ],
  "session" : {
    "durationSeconds" : 159.799141458,
    "endedAt" : "2026-06-06T16:50:02.977Z",
    "id" : "4a1f8229-6a19-4e55-8fd4-af979b706ecd",
    "initialMode" : "cameraOnly",
    "initialPipPosition" : "bottomRight",
    "slug" : "fluffy-moments-flash",
    "startedAt" : "2026-06-06T16:47:23.223Z"
  }
}

We also write a local diagnostics.json full of per-tick timing data and — because a lot of camera and encoder gremlins originate deep inside weird bits of macOS — we grab a slice of the macOS system log for the recording and temporarily write it to disk to help with debugging.

5. When recording’s finished

When the server receives the POST to /:uuid/complete it already has all the segments on disk and is serving them as an HLS playlist on the public URL. So the complete signal just causes recording.json to be stored server-side, with some of its key data added to the database record. It then kicks off a series of step-by-step post-processing jobs.

Healing

Healing is the recovery mechanism for HLS segments that didn’t make it during live recording. The server knows what segments it has on disk and now it has the client’s segment log from recording.json it can compare the two and ask the client to resend any missing or broken segments. The mac app also re-checks on launch: if a recording from the last few days still has segments that never made it up it quietly finishes healing them in the background.

Restitching

The first and simplest post-processing task is stitching the M4S segments into a single source.mp4 using ffmpeg. As soon as we have a valid source.mp4 available, we serve that to viewers instead of the HLS playlist. We also use ffprobe to extract some metadata from the new MP4 and update the database record.

Audio Enhancement

Next, we clean up the audio by running it through a chain of ffmpeg filters, writing the result back to the audio track of source.mp4. I’m still working on getting this right but at the moment the chain involves:

A high pass filter to remove really low frequency noise.
arnndn to denoise speech.
afftdn to clean up stationary background noise.
An agate noise gate to silence parts where I’m not speaking.
dynaudnorm for volume levelling within the regions where I am speaking.
A final loudnorm to produce a normalised volume of about -14 LUFS.

We also generate a peaks.json from the audio levels, used by the video editor to render a nice waveform and suggest quiet areas to trim or cut.

Thumbnail candidates

Multiple frames are extracted and scored by luminance variance, with the “best” one written to disk as thumbnail.jpg and used as the video’s poster image. The other candidates are also saved to disk on the server so I can choose a new one in the admin app if I want.

Generating video variants

We use source.mp4 to generate downsized variants so we can serve them to viewers who want lower resolution versions. If our source is 1080p we just generate a 720p.mp4 version. If it’s 1440p we’ll create both 720p.mp4 and 1080p.mp4 derivatives. And so on.

Generating storyboard images

For videos longer than 60 seconds we generate a storyboard.jpg and storyboard.vtt so the player can use them to show previews when scrubbing the timeline. Longer videos are sampled less frequently than shorter ones so they don’t get too enormous.

We also generate a second, more granular storyboard image and VTT for use in the admin app’s video editor.

Suggested edits

We look at the peaks.json and if there are any obviously quiet areas we write a suggested-edits.json which is picked up by the video editor and used to suggest trims and cuts when it’s first opened. This is deleted when any actual edits are made, and automatically cleaned up after a few days if not.

Transcription & Subtitles

While the post-processing above is done server-side, doing any AI stuff on the server would mean paying for tokens on an external service or beefing up the server enough to run models on it. Since I have a pretty powerful laptop it makes more sense to do this locally instead, so the macOS app includes WhisperKit for transcription and makes use of Apple’s built-in foundation models for title suggestions.

When a video completes, the macOS app kicks off a task to transcribe the local audio.m4a using WhisperKit. It uses this and the timing data from recording.json to produce two things:

A words.json containing each word and its start & end timestamp.
A captions.srt containing timestamped subtitles.

Both are stored locally and also sent to the server along with the plain transcription text. The plain transcription is written to the database and captions.srt is used to provide subtitles in the video players. We only use words.json in the video editor, but it’s good to keep around as a definitive version of the transcript.

Suggested title and description

If transcription completes successfully, the first ~500 words are fed to Apple’s local Foundation Model along with a system prompt asking for a suggested title. The prompt includes some data from recording.json and the response is checked against some simple is-this-insane? rules before being sent to the server where it’s used to update the video’s title in the database (unless I’ve already touched it).

A similar process is used to suggest a description and, if chapter markers exist, suggest titles for each of them.

This is far from perfect, but it’s better than nothing at all.

So where do we end up?

On the server-side, the whole post-processing pipeline is managed by a kind of step registry which ensures each step happens in order and allows me to manually retrigger the process from various points if I need to. When everything’s finished the admin panel will show a checklist like this.

We’ll end up with the following in our database record…

Field	Description	Example Value
id	UUID, primary key.	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
slug	Current URL slug. Unique. Old slugs live in `slug_redirects` for 301s.	`how-to-use-the-new-dashboard`
status	`recording`, `healing`, `processing`, `ready`, `reprocessing`, `processing_failed`, `incomplete` or `deleting`.	`ready`
visibility	`public`, `unlisted` or `private`.	`unlisted`
title	Display title. Null until set by the user or the AI suggestion step.	`How to Use the New Dashboard`
description	Public-facing description. Null until set.	`null`
notes	Private notes.	`null`
duration_seconds	Cached at completion so list views don’t need to sum segment durations.	`187.4`
width	Pixel width of `source.mp4`, from ffprobe.	`2560`
height	Pixel height of `source.mp4`, from ffprobe.	`1440`
aspect_ratio	Width / height, cached for layout work.	`1.778`
file_bytes	Size of `source.mp4` in bytes.	`48291840`
camera_name	Camera device name captured from `recording.json`.	`FaceTime HD Camera`
microphone_name	Mic device name captured from `recording.json`.	`MacBook Pro Microphone`
recording_health	Summary of any recording issues (dropped frames, failed segments). Null if clean.	`null`
source	`recorded` (from the macOS app) or `uploaded` (via the admin web upload).	`recorded`
created_at	Row creation timestamp (ISO-8601).	`2026-04-30T14:22:03.841Z`
updated_at	Last update timestamp (ISO-8601).	`2026-04-30T14:29:17.205Z`
completed_at	Set the first time the video reaches `ready`; never overwritten afterwards.	`2026-04-30T14:25:44.012Z`
trashed_at	Set when the video is moved to the trash bin; null otherwise.	`null`
last_edited_at	Set when edits are committed via the video editor; null if never edited.	`null`

The video_transcripts table will also have a row for the video with the plain text transcript and word count.

On Disk

Our server’s storage volume will have a directory which looks something like this…

Our mac will have a directory in ~/Application Support/LoomClone/recordings/[UUID] which looks something like this…

And when someone visits the public URL for the video they’ll see something like this, complete with subtitles, thumbnail, scrubber previews and the option to play lower-resolution derivatives.

There’s a lot I haven’t covered here – I’ll hopefully get to that in some more focussed articles in the future. If you’re interested in the details of all this the internal docs on GitHub might be of interest. Just bear in mind much of it was written by an LLM.

Because we keep these locally and know they failed, we can retry them later as part of the “healing” process. ↩

An actual homepage for this site (finally)

Thu, 23 Jul 2026 00:00:00 GMT

Over the last month or two I’ve been trying to finally get this site to a place where it feels finished enough for the moment. For my personal website this basically equates to nothing annoys me about it and nothing on the backlog feels like it’s hanging over me.

I’ve really enjoyed picking away at this because it’s been a real mixture of random stuff I’m interested in right now and ideas which I recorded as GH issues years ago.

While I’ve written about some of this, I was having too much fun to stop and cover much, so I can only really point you at the styleguide, which does a decent job of demonstrating a lot of it. Or the commit history.

Looking back at my task lists and GH issues it’s pretty clear I’ve shied away from two jobs for bloody ages:

Putting some proper thought into the typefaces and how I use them.
Redesigning the homepage (#25, Apr ’25).

Which is unsurprising because they both require Actual Non-Trivial Taste-Based Decisions About My Own Website. Anyone reading this who’s ever had “redesign personal site” on their todo list will know that such decisions are orders of magnitude more difficult than any genuinely-weighty decision required at work. 🤷‍♂️

So I’m happy to say that I’ve just ticked the last one off. The homepage of this site now contains more than a simple list of links.

I’ve always had a soft spot for the “skeuomorphic” faux Sellotape, stitched corner banners and ripped paper effects which everyone loved twenty years ago. So while the homepage shows recent articles in the usual type-as-design style, I couldn’t resist showing notes as little bits of dot-grid paper with a torn right edge – both on the homepage and on the notes index.

Before starting on #151 I tried to lay some groundwork by standardising the various card components but still ended up tweaking a bunch of stuff while working on the homepage, including the addition of global CSS view transitions. The PR description has a decent list of all the little bits which happened by accident.

Aside from “clearing the backlog”, it’s been lovely having actual time in this codebase. That might sound weird considering how simple it is – especially since AI has been writing much of the recent code here – but I don’t ever remember having the time and headspace to kinda settle in to my own site’s code in a kinda intuitive, somehow fundamental way¹.

I still have a ton of fun ideas I wanna play with on this site, but boy does it feel good to finally clear the backlog and have nothing I feel I should do here. This site was always intended as a playground but it’s hard to really enjoy playing when you’re avoiding that awkward new roundabout & slide you gotta deal with sometime.

I feel like working with AI coding agents has probably made this possible, because for every session I’ve spent working on this site at least 3/4 of it has been reading and thinking, not writing code. Which is a luxury one rarely gets on a personal website. ↩

Introducing my very own Loom

Tue, 07 Jul 2026 00:00:00 GMT

Over the past couple of months I’ve been building a personal video-sharing platform to replace Loom, partly so it works how I’ve always wanted Loom to work and partly so I have long-term control over my own videos. Its basic functionality is broadly equivalent to Loom minus the stuff I never use, plus some me-specific extras. Building what I’m currently calling LoomClone has been mad fun and I’ve learned a ton (this is my first proper native macOS app, among other things).

Before we dive in, here’s what one of these videos looks like embedded on this site…

30s 18 June 2026 Open

I’ve been a huge fan and paying customer of Loom since their very early days and have always had two main use cases:

Quick, short screenshares and talking head videos where I hit stop and immediately paste the link into Slack, Notion, Asana, WhatsApp or similar. For this kind of video-based async communication to work, it must be frictionless for both me and viewers. Loom was the first product which could do this reliably.
Longer, more polished videos for tutorials, guides, presentations and the like. These often end up embedded in evergreen Notion/Google docs and tend to be widely linked to from all sorts of places. When I say “more polished” I don’t mean the hours-in-final-cut-pro polish I might put into a marketing video. More like preparing for an All Hands or training session on Zoom: I’m gonna prep an outline & some slides, tidy up my desktop, make sure all my demos and other windows are in the right place, maybe do a quick run-through and then record in one take. My default approach to this with Loom has always been to line up any slides or apps I need in fullscreen spaces and swipe between them as I record, adding any important talking-head segments by recording separate Looms and then stitching them together in Loom’s web editor.

Loom’s whole business is built on being brilliant at (1) and while they do (2) kinda-okay I’ve always had some gripes about their product, my biggest being…

I don’t own the canonical URLs for my videos. I’ve got hundreds of historical Loom videos, many of which are embedded in documents, wikis, knowledge bases and archived slack channels in organisations I’ve long-since left. Every one of them points to loom.com/something, so while I own my actual videos (I can download them), Loom controls what matters most for content on the web: the canonical URLs.
I don’t have much control over the viewer experience. Loom controls how my videos are served to viewers: It’s impossible for me to control things like RSS feeds, custom embed players, SEO and text-based endpoints to the degree I want.
The camera feed isn’t first class unless I’m in cam-only mode. Most of my longer videos involve cutting between talking-head and screenshare segments. Loom doesn’t let you do that with a fullscreen, high-quality camera feed mid-recording. This has always been mega frustrating for me.
Reliability & Recomposability. Loom recordings rarely fail, but when they do it’s invariably a 30-minute single take in which I was fucking inspired and will never repeat quite as well after picking my smashed laptop off the floor. If you’ve been here you know how that feels. And it’s only slightly less frustrating to realise a whole segment which should’ve been talking-head is actually a recording of my empty desktop with a voiceover on top. And there’s nothing I can do because the camera feed wasn’t even captured.
The mac app is not a mac app. Loom’s macOS app is built on Electron and bundles a custom build of ffmpeg alongside the usual Chromium. I get why they do this but as I’m always on Apple Silicon, a proper native mac app is likely to be way more performant for heavy stuff like video capture in all sorts of ways (even before taking advantage of lower-level OS APIs).
All the features I don’t want. Any product with a wide audience will have features I don’t want. I’m cool with that even though I can’t turn many of them off. But in 2026, any product like Loom will likely have features nobody at all wants because a) it can never be finished unless it’s been abandoned, and b) it’s gonna be stuffed full of nonsense AI features.

I tried switching to Cap because it’s open source and I can use my own domain, but while it isn’t terrible it doesn’t feel like a platform I wanna bet on long-term. And so we arrive at the thought… what if I built my own? 🤔

Which is just what I’ve been doing…

📜

Core Principles

Given the massive potential for scope creep here, I started by defining some core principles. These underpin almost all the product decisions I’ve made along the way.

Instant Shareability. The moment I stop recording, I need a working URL which I can share immediately. This is what differentiates async video comms tools from other recording and hosting apps.
Never Lose Footage. The product must guarantee that footage is recoverable. Recording a 20-minute tutorial and losing it thanks to connection or server problems isn’t okay. The whole thing should be fault-tolerant by design.
Permanent URLs which I own. A video URL works forever. If I change a video’s slug, the old URL redirects to the new one. Videos embedded in Notion pages, Google Docs, and knowledge bases years from now must still work. Every video lives on v.danny.is, a domain I control.
Reliability for Viewers. When someone clicks a video link, it Just Works regardless of device, location, connection etc. Viewer-facing video delivery must be first-class.
Discoverability & Viewer UX. I’m a good web citizen. The public-facing endpoints serve semantic content which works in a variety of contexts. Public videos are SEO-friendly and are discoverable via RSS feeds, LLM-facing endpoints and the like.
Simplicity. The whole system is designed with one goal in mind: allowing me to record, host, and share videos. Every feature must be in service of doing these things really well. Similarly, the codebase and technology stack should be as simple as possible.
I’m the Only Creator Here. This product is only for me. Nobody else will use the mac app or admin app. Nobody else will record videos. The only parts where other people matter are the public-facing bits where folks find and watch my videos.

The Four Moving Parts

It’s helpful to think about LoomClone as four separate things, each with a distinct purpose and set of user needs. While this isn’t quite accurate when it comes to the underlying tech, it’s the framing I’ll be using in this series of articles.

The macOS recording app. A native macOS menubar app for recording videos with as little friction as possible. Its only job is helping me get set up for a recording quickly and then streaming it up to the server once I hit record while dealing properly with all the pausing and mode switching that happens during recording.
The backend API. A web API which receives data from the mac app and handles storage, background post-processing, backup, error recovery and the like. Its job is working with the mac app to get recordings on a server and ready for public consumption in a reliable way.
The admin app. A web interface for managing, editing and working with my videos, optimised for the workflows I personally care about most. Ideally, I’ll rarely use it but when I do, its job is to make whatever I need as easy and painless as possible.
The viewer-facing surface. Serves videos to viewers in the best way for them and handles everything else that has to do with publishing, discoverability etc.

We’ll go into detail about how these work later but for now it’s important to explain exactly what they do from a user perspective. So the next half of this article is dedicated to the recording app UI and viewer-facing surface, finishing with a 4-minute lightning tour of the admin app and its features.

The macOS recording app

The menubar app is deliberately very simple. Clicking it opens a popover like this.

Here’s what each control is for…

Control	Description
Display	The monitor to use for screen recording
Camera	The camera to use
Mic	The microphone to use
Preview	Shows how the recording will look (based on the starting mode selected below) so I can confirm the right sources are selected and are looking good
Sound meter	For the selected mic so I can check I have decent audio levels
White balance	Adjust the camera white balance. I often want to tweak this depending on the current lighting conditions
Brightness	Adjust the camera brightness
Starting mode	Choose between screen-only, camera-only and picture-in-picture mode. This only affects the preview above and the mode in which the recording will start. I can toggle between these freely while recording.
Upload quality	Choose the quality of the uploaded recording ( 720p, 1080p or 1440p)
Upload framerate	Choose the framerate of the uploaded recording (30 or 60fps)

The UI adapts appropriately to the three selected sources: if camera or display is set to “None” the mode toggle is disabled; the camera controls are hidden when no camera is selected; the sound meter is only visible when a mic is selected. The upload quality and framerate toggles also respect the available feeds – a camera delivering 1080p/30fps with no display selected won’t show higher options for the upload quality because we’d just end up with an upsampled upload.

Here’s what it looks like with Camera mode selected and the preview showing the full camera feed. Expanding the Hide from recording section allows me to hide stuff from the screen recorder.

Control	Description
Desktop icons	When checked, Finder’s desktop icons will be hidden in the screen recording
App Windows	Any checked apps will have their windows hidden in the screen recording. Currently running apps are shown alongside the five most-recently selected apps (whether they’re running or not)

The Record button shows a short countdown and begins recording.

The UI while recording

During recording, a floating toolbar is shown at the bottom of the screen.

From left to right the controls are…

Control	Description
Stop	Finishes the recording
Pause/Unpause	Pauses the recording. I use this all the time during longer recordings while I reorganise windows, switch to different spaces or quickly check my notes
Add chapter marker	Adds an anonymous chapter marker. If my recording has multiple chapters to it I can hit this to add markers which can later be named in the web interface
Cancel	Cancels the recording and deletes any data already on the server
Mode switcher	Switch between screen-only, camera-only and picture-in-picture mode mid-recording
Recording length	Shows the length of the recording so far

When in a camera mode a draggable preview of the camera feed is shown as an overlay while recording. This is circular when in screen-and-camera and rectangular when in camera-only mode.

Neither the camera preview nor toolbar are captured in the actual screen recording, but dragging the camera preview between quadrants of the screen will cause the camera overlay in the final recording to move to that corner of the screen.

Besides the settings window and a few warnings which pop up if something goes wrong while recording, this is the whole UI of the macOS app.

The viewer-facing surface (a quick tour)

As soon as I’m finished recording a video, it’s available on a randomly-generated public URL like https://v.danny.is/three-random-words/. Here’s what the page for the video at the top of this article looks like.

It shows the title, length and date at the top (plus any public tags – more on that later) with a large video player below. The video player works exactly as you’d expect, including closed captions, thumbnail scrubbing and the like. The description and a simple footer are shown underneath.

While the page is intentionally simple, fully controlling its underlying code means I’ve been able to ensure these URLs embed properly in Notion and Google docs, have appropriate rich preview data when shared, and – for public videos – are discoverable via appropriate SEO, RSS feeds and the like.

Here’s a quick 3-minute run-through of the video player itself, plus a few little easter eggs.

3m 13s 6 July 2026

The only other part of the public surface I should mention is tag pages, but first a note on visibility…

As we’ll see shortly, tags mainly exist to help organise my recordings in the admin app. But like videos themselves, tags can be private, unlisted or public. And public tags have their own tag pages which serve as public collections (or playlists) which look like this.

We’ll dig into some of the more interesting features and subtleties of the public surface in subsequent articles, but for now I wanna give you a quick tour of the admin app for all this.

The admin app, a lightning tour

I’ll do a whole article on the admin web app in due course, but since I’ve now got a fancy video platform I might as well give you a lightning tour in video form! Here’s a four-minute demo…

Admin App Lightning Tour

4m 23s 6 July 2026 Open

Wrapping up

At the time of writing, LoomClone feels pretty much feature-complete. I’ve still got a little work to do on audio post-processing & recording performance, but the only new features I’m considering are auto-expiry and watermarking, both of which are pretty trivial.

By far the most interesting parts of this project are under-the-hood, but hopefully this introduction to what LoomClone does will set the scene for the next few articles about how it works.

Vibe coding an iOS app to publish notes here

Tue, 30 Jun 2026 00:00:00 GMT

I currently publish two kinds of content on this site: articles and notes. I write all my articles in Astro Editor, with in-progress work committed to main as drafts and pushed to GitHub regularly. When I’m ready to publish an article I have Claude Code check for spelling errors, flip the draft toggle and – after checking it looks okay on my local dev server – commit and push. Pushes to main trigger a GitHub action which rebuilds the static site and redeploys it.

This process works great for articles, especially since I now keep two local copies of this repo: one for working on the site’s code (which is often not on main) and one for working on content (which is always on main).

This also works great for notes like this one which are basically mini-articles, but it’s not ideal for ones like this which are responses to stuff I found online.

When I find something interesting online I want to open Astro Editor, create a new note, paste the URL I found into sourceURL and then type my comments… that’s way too much faff.

There’s gotta be a chrome extension for that?

I think this was actually one of the first things I fully vibe-coded. It’s a Chrome sidebar extension which grabs the URL and title of the current tab and lets me add some notes. Hitting save writes a new draft note to my local copy of this site with appropriate frontmatter and filename.

The textarea supports markdown & keyboard shortcuts, and the Add Highlight button grabs the selected text from the page and adds it to the textarea as a blockquote. This works great when I wanna comment on multiple quotes from an article.

Notes created this way obviously won’t go live until I’ve removed draft: true, committed and pushed. I can live with that – it only takes a few seconds and if I forget, it’ll happen when I’m next in the repo.

I use Astro Editor and this Chrome extension on my desktop machine, and both are designed to work with local files on it. This works because I’ll always have a local copy of my website’s repo, and the tooling to quickly commit and push.

This is not so on my iPhone…

Vibe coding my first personal iOS app

I do not like writing on my phone and am never gonna use it to work on articles or long notes for this site. The closest I’m likely to get is the scrappy thoughts that might someday make it to this site, for which I use Obsidian.

The only phone-based thing I wanna do re. this website is quickly create (and sometimes publish) short notes about the thing I’m reading. And damn have I realised I wanna do that a lot.

I probably do eighty percent of my online reading on my phone and while I have a perfectly good system for clipping stuff into Obsidian, I almost never remember to share it here afterwards.

What I need is something similar to my chrome extension, but on my phone. And since I don’t have a local copy of this website on my phone it will need to write directly to GitHub.

So I (mostly) vibe-coded a little iOS app specifically for this…

How it works

The app ships with a Share Sheet extension which lets me save a new draft note from pretty much any app. If there’s a URL or title available they’ll be passed to the app along with any notes I type into the share sheet. The notes field will be pre-populated with any selected text.

Opening this note in the actual app looks like this. The title, sourceURL and body fields have been properly populated and a suitable filename has been generated. We can also see a link preview for the source URL.

The body field supports simple markdown formatting and can be expanded for easier writing.

All new notes are created as Local Drafts and stored as Swift data on the device. These can be created, edited and deleted in the app.

Getting notes to GitHub

When the app loads, it fetches all my notes via the GitHub API, parses the relevant frontmatter and stores them in the app. Published notes get a green label while unpublished drafts get an orange one.

When I’m done with a local draft I have two options: I can push it to GitHub as a draft or publish it immediately. In both cases the app uses the GitHub API to make a new commit adding the new note to the repo – publish just removes draft: true from the frontmatter.

I originally planned to leave it at this but I can easily imagine pushing a new note and then spotting an error in it, so it’s also possible to edit and delete notes. Published notes can be “unpublished”, which makes a new commit adding draft: true and unpublished drafts can be published by doing the reverse. Notes can also be permanently deleted via the app, but I can’t see myself doing that very often.

Any note which exists on GitHub and is later edited in the app is marked as having local changes and I have the option to either update the note on GitHub with those changes or overwrite the local data with whatever is on GitHub. There’s also a tiny bit of cleverness to deal with notes which have been updated on GitHub and ensure the local data is updated on sync.

Here’s the code if you wanna have a nose…

GitHub - dannysmith/dannyis-notesapp-ios: Vibe-coded personal iOS app. Experiment

Vibe-coded personal iOS app. Experiment. Contribute to dannysmith/dannyis-notesapp-ios development by creating an account on GitHub.

github.com GitHub

Building Apps for One

The initial build of this took about two hours, most of which was me getting clear on what I actually wanted and adequately explaining that to Claude Code. I’ve probably spent another ninety minutes or so glancing over some of the code and iterating with Claude on the visual design.

I’d probably never have bothered building this before AI models got good at coding, but if I had I would certainly have tried to make it usable for people other than me.

The biggest reason I was able to get this done so quickly is the number of decisions I didn’t need to make because this only needs to work for me. All the info about my Astro site is hard-coded, as are the fields for my notes schema. I auth with GitHub via a scoped Personal Access Token, not a complex OAuth flow. It’s only been tested on an iPhone 15 Pro because that’s the only device it’ll be used on. The UI is designed to my taste alone. And so on.

But perhaps most exciting for me is that I’ve just built my first iOS app in under three hours. And while I only hand-wrote about four lines of code, the simplicity inherent in such a tightly-scoped App for One means I’ve read and understood most of it. That, plus working in a tight feedback loop with Claude Code has allowed me to learn a lot of new things very quickly here.

Making this Astro site more Agent-Friendly

Thu, 18 Jun 2026 00:00:00 GMT

For the last few months I’ve been tinkering with improving this site for AI agent consumers and after reading Dachary Carey’s article on Astro’s removal of llms.txt I went down a bit of a rabbit hole, finding Joost de Valk’s “agent-ready” piece along the way. Here’s the result of that little side-quest.

Existing “agent friendly” features

This site has always had stuff to help machines understand its content: it has sane, predictable URLs, seo-friendly meta tags and <link rel="canonical">. A sitemap is generated by @astrojs/sitemap and the three RSS feeds are advertised on every page. The markup is semantic and includes an appropriate sprinkling of microformats and schema.org stuff. All pages have sensible OG data and auto-generated OG images. I also publish machine-readable records over AT Protocol. Some of this is legit helpful for AI User Agents but over the last year I’ve also added stuff specifically for them…

Markdown versions of my content

Every article and note has a static .md version so appending .md to any URL will return a markdown version of the page (try it for this article). I also include “copy / open as Markdown” buttons at the end of every post, though that’s mainly for humans copypasta’ing into chat interfaces.

An `llms.txt` index

I generate an llms.txt at build time which includes:

A brief intro about me and this website.
Links to important external identities (socials etc).
What I’m doing now, pulled from my now page.
A list of all the articles and notes as markdown links.
A list of other pages, including the styleguide.

You can see it live here.

JSON-LD

I include a full JSON-LD @graph of structured data in every page which includes Person, Organization and WebSite, plus BlogPosting for content pages.

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@graph": [
      { "@type": "Person", "@id": "https://danny.is/#person" },
      { "@type": "WebSite", "@id": "https://danny.is/#website" },
      { "@type": "BlogPosting", "headline": "…", "datePublished": "…" }
    ]
  }
</script>

Auditing for Agent Friendliness

Dachary Carey’s afdocs tool checks against the spec at agentdocsspec.com, which is primarily designed to ensure content is agent-readable and navigable. Cloudflare’s isitagentready.com is more focussed on conformity with emerging agent discovery standards. Running bunx afdocs check http://danny.is --verbose yielded these warnings & failures, while isitagentready.com gave me a pretty shit score and recommended a bunch of potential improvements.

As with most automated audit tools, these are blunt instruments with very little context about this website. So the goal here isn’t improving scores, it’s using the data to actually improve the site.

Better Agent-Friendliness

Here’s what I actually did off the back of these two audits:

1. Update `robots.txt`

I updated my robots.txt to use the Content Signals convention:

User-Agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /

This is a preference signal, so the AI firms will probably ignore it.

2. Have every page point at `llms.txt`

My llms.txt exists purely to tell AI agents how to get what they need from this site, so it’s super important that they can actually find it. The HTML for an article looks something like this:

<head>
  ...
</head>
<body>
  <main>
    <article class="h-entry" itemscope itemtype="https://schema.org/Article" >
      ...
    </article>
  </main>
</body>

Which means any agent using a WebFetch tool that returns markdown is unlikely to see anything outside of <main>. If we want every fetch to include a pointer to llms.txt, it’s not enough to have a link in our <head>.

I now insert a LLMDiscoveryNote.astro component immediately after the opening <main> on every page. It’s pretty simple:

<p class="sr-only">
  For AI agents and crawlers: a structured index of this site is available at
  <a href="https://danny.is/llms.txt">https://danny.is/llms.txt</a>.
</p>

We should do the same for our markdown versions. Let’s add this to the top of them all:

> For the complete site index, see [llms.txt](https://danny.is/llms.txt)

3. Serve markdown to UAs asking for it

Since user agents can send an Accept header with their requests and we already have markdown versions of our content, we should probably serve markdown to anyone requesting plain ol’ /writing/<slug> URLs with an Accept: text/markdown header. We can do this for both notes and articles with a little addition to our vercel config:

{
  "src": "^/writing/([^/]+)/?$",
  "has": [{ "type": "header", "key": "accept", "value": ".*text/markdown.*" }],
  "dest": "/writing/$1.md",
  "headers": { "content-type": "text/markdown; charset=utf-8" }
}

Browsers never send Accept: text/markdown so they’re unaffected by this, but we need to make sure “negotiable URLs” like this carry Vary: Accept so CDNs don’t accidentally serve markdown when they shouldn’t.

While we’re here, we can also respond to Accept: text/markdown requests to the root of danny.is with the contents of our llms.txt rather than our homepage HTML.

4. Advertise the index Even More

Since llms.txt is so important, let’s also add a Link header to every response and a <link> tag to every HTML document:

Link: </llms.txt>; rel="describedby"

<link rel="describedby" type="text/markdown" href="/llms.txt">

5. Make it easier to discover markdown versions

Our llms.txt currently includes a big old list of markdown links to all our content, but the URLs point at the HTML versions. It makes much more sense to use the .md URLs in this context. So now the links in llms.txt point to markdown versions if they exist.

While we’re here, we should make sure content pages include a <link rel="alternate" type="text/markdown" href="<markdown version>.md">.

6. Turn meta-refresh redirects into propa HTTP redirects

I use redirects in two places on this site:

Those hard-coded in redirects.ts which forward URLs like https://danny.is/meeting to external services.
Articles with a redirectURL frontmatter property which forward to content hosted elsewhere.

I use Astro redirects for the former and meta-refresh for the latter, though since this is a statically generated site they all end up as HTML meta-refresh pages in the generated /dist.

We can improve on this by having our astro build also generate a host-agnostic dist/redirects.json containing all of these, in this kinda form:

{
  "version": 1,
  "redirects": [{ "source": "/meeting", "destination": "https://cal.com/dannysmith", "status": 302 }]
}

Then as part of our Vercel-specific deployment action we can use this to generate an appropriate Build Output API config which returns proper 302 redirects for these routes. The meta-refresh pages stay in the static build for the sake of portability, as does dist/redirects.json which is the source of truth about how server-side redirects should work.

So where did we end up?

These little tweaks ended up making quite a difference to our audit metrics.

→ bunx afdocs check https://danny.is --verbose
...
16 passed, 3 warnings, 3 failed, 1 skipped (23 total)

The remaining warnings & failures are all false positives as far as I’m concerned. The isitagentready audit jumped from a score of ~20 to 43 overall, with all the things I care about now showing “green” (check it out).

Most of the “failures” here have to do with API, Auth, MCP & Skill Discovery. Not only are these extremely new/immature standards, they’re also not very relevant to content-first websites like this one.

Wrapping up

None of this was difficult to do, but it did require a few minutes actually thinking about how agents consume content on a site like this. I think my biggest takeaway here is that it doesn’t really matter whether /llms.txt is adopted as a standard by harness-makers, in the same way it doesn’t really matter about RSS vs Atom feeds. But it does matter that I – as a website owner – do my best to signpost users appropriately so they know where to find stuff.

Speeding up Astro builds and improving deployment

Sun, 14 Jun 2026 00:00:00 GMT

When I first started moving this site to Astro I decided that I wanted a truly statically-generated site. In other words, I want astro build to produce a folder of plain old files which can be served by any webserver which can serve files. So while I currently deploy to Vercel, nothing about the build depends on Vercel. This means I can use a GitHub Action to build the site and then dump the resultant dist/ on Vercel (or anywhere else I want).

I’ve been doing a lot of work here recently and noticed two problems:

Slow builds. Every time I push to main I have to wait for ages. Builds were taking upwards of five minutes from push to deploy, with astro build alone taking 4m 30s.
Rubbish Caching. Just dumping a static site meant Vercel was serving everything with cache-control: public, max-age=0, must-revalidate headers, including content-hashed assets and static files like fonts. The lack of Vercel config was also preventing my custom 404 page from being served and there were a few other little bits which are only possible to fix by configuring how my files are served by Vercel.

Before looking at anything else we should see if we can reduce the weight of our build-time dependencies. Individually this is unlikely to make a huge difference to build time but it’s good hygiene and reduces supply-chain risks to boot.

I ended up removing some old unused packages and moving a bunch to devDependencies since they’re not needed at build-time. I replaced unfurl.js with a small utility function, and noticed that while I was using Playwright for end-to-end tests & rendering mermaid diagrams, I was also loading puppeteer to grab screenshots in a scraper script. Since puppeteer bundles Chromium that’s not ideal, so now I’m using playwright everywhere.

Speeding up the Astro build on GitHub

Three jobs run per push (all defined in deploy.yml): Check → Build → Deploy. Measured on a real run against main I got:

Job	Time	The expensive bit
Check	102s	Playwright install ~23s, e2e tests ~30s
Build	313s (5m 13s)	`astro build` was 4m 30s of it
Deploy (prod)	48s	`npx vercel` re-downloading the CLI took ~24s

Inside astro build, two phases were the main culprits and both are cacheable across runs:

Phase	Time	What it is
OG image generation	92s	167 images @ ~553ms average
Image optimisation	2m 4s (124s)	312 transforms (avif + webp + jpg) from ~100 source images

Together, these account for about 80% of the actual build time and ~70% of the Build job. On top of that, the build job waited for the check job to finish before starting, which added about 100s to every run.

Fix 1 — Cache `node_modules/.astro`

GitHub Actions gives every job a clean machine. To carry files between runs we can use actions/cache, which takes a path and a key to store it under. On the next run, if a cache exists for that key it gets restored to path. I was already doing this for Playwright’s browsers, which are slow to download:

- name: Cache Playwright
  uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: playwright-${{ runner.os }}-${{ hashFiles('**/bun.lock') }}
    restore-keys: |
      playwright-${{ runner.os }}-

This is a common pattern: the key is a hash of bun.lock, so the cache is reused until any of my dependencies change, at which point the key changes and fresh browsers are downloaded and re-cached. The restore-keys line is a prefix fallback — if there’s no exact match, GitHub restores the most recent cache whose key starts with playwright-<os>-, so a dependency bump still starts from a recent cache rather than from nothing.

Astro keeps its own cache in node_modules/.astro/ and the useful part for us is how it handles images. Every optimised image is written out with a hash of the source file and its transform baked into the filename. So when Astro goes to optimise an image, if a file with that exact hash already exists, the work is already done and it skips it.

Astro does this on disk but I wasn’t caching this across builds so every image was regenerated on every build. The fix is obvious: persist node_modules/.astro/ between runs with actions/cache, like we did with Playwright. The only interesting question is what to key it on?

It’s tempting to copy the Playwright pattern and key on a hash of the content (hashFiles('src/content/**') or similar), but that throws away the entire image cache the moment any content changes, which is most pushes. So instead I’m keying on the commit SHA which is unique to every push. Combined with the restore-keys prefix fallback, this means:

Every successful run writes a fresh cache snapshot under its own SHA (remember, keys are write-once).
Every run restores the most recent snapshot via the prefix, regardless of what changed.
Astro’s own per-image hashing then re-processes only the images that actually changed.

- name: Cache Astro build output
  uses: actions/cache@v4
  with:
    path: node_modules/.astro
    key: astro-cache-${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      astro-cache-${{ runner.os }}-

This is the pattern withastro/action uses and it drastically sped up my build times.

Fix 2 — Add a file-cache to OG image generation

Astro’s content-addressed caching only applies to its own image optimisation, and my OG images are generated by an Astro endpoint (a .png route that renders each post’s social-share image with satori and resvg). Astro doesn’t cache this kind of thing, so even with node_modules/.astro/ cached on GH Actions, every build re-renders all the OG images from scratch.

What if we also cached these files to node_modules/.astro/ in a similar way to Astro’s image cache?

Before rendering, we hash everything that affects the image and then if a PNG already exists for that hash, we return it; otherwise we render it, write the PNG, and return it. Here’s the gist of og-image-generator.ts:

const CACHE_DIR = path.join(process.cwd(), 'node_modules', '.astro', 'og-cache');
const CACHE_VERSION = 'v5';

// Content-addressed cache key: any change to the data, template, or
// dimensions produces a different key, so edits regenerate the image.
const cacheKey = createHash('sha256')
  .update(JSON.stringify({ data, template, width, height, v: CACHE_VERSION }))
  .digest('hex');
const cachePath = path.join(CACHE_DIR, `${cacheKey}.png`);

// Cache hit — return the previously rendered PNG.
try {
  return await fs.readFile(cachePath);
} catch {
  // Miss (or unreadable) — fall through and generate.
}

// ... satori + resvg render ...

// Cache the successful render
try {
  await fs.mkdir(CACHE_DIR, { recursive: true });
  await fs.writeFile(cachePath, pngBuffer);
} catch (cacheError) {
  console.warn('Failed to write OG image cache:', cacheError);
}

A few things make this safe to do:

It’s only safe to content-hash because the render is deterministic. I embed static TTF fonts straight into satori({ fonts }) rather than letting it fetch them, so identical inputs always produce a byte-identical PNG. If the fonts came over the network or from the system, the same inputs could render differently and a content hash would be a lie.
The key contains everything that affects the output — data (the post’s title, description, url and type), the template name, and the dimensions. Editing a post’s title means only that image is regenerated.
CACHE_VERSION is a manual override. Things that are the same for every image (template markup, branding etc) aren’t in the per-image key, so if I change how the OG images look none of the keys will change and I’d end up serving the old cached versions. Bumping CACHE_VERSION changes every key at once so I can just bump this to invalidate the whole lot.
Writes are best-effort and the fallback isn’t cached. A failed cache write never fails the build, and if satori falls over and we render a simpler Sharp-generated fallback instead, that is deliberately not cached.

Fix 3 — Run Check and Build in parallel and only deploy after both

The check job just runs bun run check:all which basically does this and fails if any checks fail:

tsc --noEmit &&
astro check &&
prettier --check . &&
eslint . &&
vitest run tests/unit &&
playwright test

The build job just runs bun run build, prepares an artifact for Vercel and uploads it using actions/upload-artifact. The deploy job grabs that artifact and drops it on Vercel.

There’s no reason at all why check and build shouldn’t run in parallel, so long as deploy waits for both of them to finish successfully.

Before: checks → build → deploy (build waited on checks, ~100s idle). After: Check and Build run in parallel, and Deploy waits on both.

jobs:
  checks:        # Starts immediately
  build:         # Starts immediately (dropped `needs: checks`)
  deploy-production:
    needs: [checks, build]      # both must pass before anything ships
    if: github.ref == 'refs/heads/main'

Fix 4 — Stop `npx` re-downloading the Vercel CLI

The deploy job ran npx vercel which fetched a fresh copy of the Vercel CLI on every deploy (adding ~24s) because ubuntu-latest no longer pre-bundles it. Pinning the CLI version in an env var and cacheing npm’s download cache means npx resolves from that instead of re-downloading.

env:
  VERCEL_CLI_VERSION: '54.6.1'

# ...in each deploy job:
- name: Cache Vercel CLI
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: vercel-cli-${{ runner.os }}-${{ env.VERCEL_CLI_VERSION }}
- name: Deploy to Vercel
  run: npx vercel@${{ env.VERCEL_CLI_VERSION }} deploy --prebuilt --prod --yes --token=${{ secrets.VERCEL_TOKEN }}

So how much faster did things get?

Measured before & after on the Build job:

Phase	Cold (before)	Warm (after)
Static entrypoints (HTML + OG)	2m 17s	48s (OG cached)
Image optimisation (Sharp)	2m 4s	~80ms (cached)
`astro build` total	4m 30s	58.7s
Build job wall-clock	4m 56s	~1m 54s

Adding some light Vercel config

Because we’re deploying an already-built site, the deploy job uses vercel deploy --prebuilt to stop Vercel trying to run its own build. This means it won’t read vercel.json – the only config consulted is .vercel/output/config.json (the Build Output API). By default this is basically empty, which is why my custom 404 page wasn’t being served and all my routes had cache-control: public, max-age=0, must-revalidate.

The solution is to include a lightweight vercel.output-config.json in the repo and have CI copy it to .vercel/output/config.json at deploy time. Here’s the whole file, block by block. Each "continue": true rule adds headers and keeps matching.

{ "src": "^/_astro/(.*)$",
  "headers": { "cache-control": "public, max-age=31536000, immutable" }, "continue": true },
{ "src": "^/fonts/(.*)$",
  "headers": { "cache-control": "public, max-age=31536000, immutable" }, "continue": true },

/_astro/* contains content-hashed JS, CSS & images, and /fonts/* contains version-stamped static font files. So our cache control can be immutable with a 1 year max-age. The filename changes every time the content does, which invalidates the cache. This alone is a huge performance boost for people viewing my site.

{ "src": "^/(favicon|avatar|avatar-circle|icon|end-mark|og-default).*$",
  "headers": { "cache-control": "public, max-age=3600, s-maxage=86400, stale-while-revalidate=86400" },
  "continue": true },

Unhashed static assets in public/ which get 1h for browsers and 1 day for edge and SWR because their URLs don’t change with their content.

{ "src": "^/.*\\.xml$",
  "headers": { "cache-control": "public, max-age=600, s-maxage=3600, stale-while-revalidate=86400" },
  "continue": true },

RSS/feeds (*.xml) get 10 mins for browsers and 1h for edge & SWR.

If you’re wondering, s-maxage is consumed by Vercel’s CDN and stripped from the responses sent to clients — so a browser only ever sees public, max-age=…, while the edge gets the longer cache lifetime.

Redirects & rewrites:

{ "src": "^/cv\\.pdf$", "status": 308, "headers": { "location": "/cv-danny-smith.pdf" } },
{ "src": "^/\\.well-known/(.*)$", "dest": "/well-known/$1" }

Redirecting /cv.pdf to /cv-danny-smith.pdf with a proper 308 only matters because some user agents won’t follow other redirects if they point to binary files. We’ll come back to the well-known line shortly.

{ "handle": "filesystem" },
{ "src": "/(.*)", "status": 404, "dest": "/404.html" }

Adding { "handle": "filesystem" } ensures that any real file in dist/ is served, which we want with a static site. The last line ensures my custom dist/404.html is returned with the proper status code for unknown routes.

Dealing with `.well-known` files

I want to serve well-known URIs from https://danny.is/.well-known/*. Right now that’s just a static security.txt and a couple of other files I’ll discuss in future articles.

It turns out that Vercel doesn’t serve dotfile directories so I can’t just generate these files in dist/.well-known and be done with it. It also turns out that Astro won’t reliably build routes placed in a dotfile dir under src/pages/. So I now keep my well-known stuff in two non-dot directories:

public/well-known/ for static files.
src/pages/well-known/ for those which need build-time generation.

Files from both end up in dist/well-known/ and the Vercel rewrite rule you saw above maps requests for https://danny.is/.well-known/* onto dist/well-known/* on Vercel.

But even if Vercel won’t serve dist/.well-known/ other webservers will so they should be in the right place in my generated site in case I decide to move off Vercel. We can achieve this with a simple postbuild script in package.json which runs

rm -rf dist/.well-known && cp -R dist/well-known dist/.well-known

Since this runs automatically after every astro build, I always get a proper .well-known/ directory.

Wrapping up

A typical content push now goes from commit to live in around two minutes instead of six, my assets finally cache the way they should, and my 404 page actually shows up. Best of all, none of this cost me the thing I cared about in the first place: astro build still spits out a plain folder of files that’ll run on any webserver.

Some Work on this Site

Thu, 28 May 2026 00:00:00 GMT

Last autumn I wrote about moving this site to Astro and have shared a few notes about little features I’ve added since then, but over the last few months I’ve picked away at a lot of little bits and pieces here which I haven’t really shown off. So I’m gonna do that now if you’ll indulge me for a minute.

I made a video platform

I’ve been building my own platform for recording and sharing videos (more on that in another post soon), so I can now add videos like this…

31s 27 May 2026 Open

Quick demo of a blog's video embedding feature

The video platform makes embedding pretty easy¹ but I wanted videos I share here to feel like first-class citizens of this site. Instead of rendering the video player from the video platform, my new LCVid.astro component renders its own Vidstack player after grabbing the info it needs from the video platform via a JSON endpoint. This obviously includes the URLs needed to embed a Vidstack player (1080p.mp4, 720p.mp4, poster.jpg, captions.srt, storyboard.jpg, storyboard.vtt), but since we do this at build-time we can also grab the title, description, length, transcript and cover image and use it to generate sensible HTML around the video player. I can use the component like this:

<LCVid src="my-video-slug" />

It supports the following props:

Prop	Description
`src`	Required. Full URL, absolute path or bare slug.
`title`	Override title.
`description`	Override description.
`aspectRatio`	Override aspect ratio.
`showTitle`	Render title above player.
`showDescription`	Render description below player.
`showMeta`	Render duration and date.
`showOpenLink`	Render “Open” link to the original video page.
`showTranscript`	Render transcript inside a collapsible `<details>`.

Code Blocks & Tables

As you just saw, I’ve also made some tweaks to how tables and code blocks are rendered. Tables just got a bit of CSS-love: they use tabular numerals, support captions and render various sorts of “header” nicely. Here’s an example:

Table 1. The numbers are made up, they’re just here to show off tabular figures.
Plan	Code	Monthly	Annual	Description
Hobby	`free`	£0	£0	For tinkering on personal side projects.
Starter	`start-25`	£9	£90	Everything a solo freelancer needs to begin.
For bigger teams
Team	`team-99`	£49	£490	Shared workspaces and roles for small teams.
Enterprise	`ent-x`	£199	£1,990	Advanced controls, SSO and priority support included.

Code blocks are rendered using Expressive Code which makes it easy to add titles and line highlights while still using markdown’s fenced code blocks. It supports a bunch of nice features including file titles and line highlights.

export function readingTime(text: string): number {
  const words = text.trim().split(/\s+/).length;
  return Math.ceil(words / 200);
}

And terminal examples are rendered in a nice-looking frame…

bun create astro@latest expressive-code-is-cool
cd expressive-code-is-cool
bun run dev

The color palette used for syntax highlighting took a little while to get right (and still isn’t perfect) but I hope it feels consistent enough with the rest of this site for the time being.

Inline Styles, Footnotes, Lists & Callouts

Inline text styles got a little love recently too. Strikethroughs are rendered ~~like this right here~~, which is fun. Keyboard elements render as little 3D keys that depress on hover: ⌘ + Shift + P. External links automatically get a little arrow, so a link to Astro looks different from a link to my notes. Abbreviations like CSS get a dotted underline and custom cursor. I’ve also made some very subtle tweaks to code, italic, bold and highlight styles.

Footnotes² have also had a little refresh. Clicking a footnote will show it immediately below the current paragraph (try it 👆) and the client-side JS for this is only served if footnotes are present.

Lists that breathe

I use lists pretty heavily in my writing. Sometimes they contain short bullets like this…

Apples 🍎
Oranges 🍊
Pears 🍐

But often each list item is much longer – more like a paragraph…

Nonsense Item One. Ea qui sint ex eiusmod Lorem commodo dolor excepteur. Commodo non magna irure labore excepteur non culpa nulla aute consequat. Excepteur aliquip esse magna fugiat. Occaecat ad est in consectetur. Exercitation ex excepteur sit eiusmod cillum exercitation reprehenderit. Aliquip do enim sunt est amet pariatur.
Nonsense Item Two. Commodo magna dolor proident pariatur cupidatat non esse proident irure laborum do culpa aliquip dolor. Sit velit culpa occaecat sunt officia. Reprehenderit duis adipisicing in incididunt nulla velit ipsum duis nostrud minim reprehenderit nisi culpa et ad.
Nonsense Item Three. Tempor dolore do adipisicing minim eu eiusmod eu sint. Adipisicing incididunt elit eiusmod in consequat et eiusmod do. Eu sit sit nostrud eu eu dolor ipsum aliquip ullamco.

These should be treated differently when it comes to vertical rhythm: lists with longer content should be spaced like paragraphs (because they essentially are paragraphs) whereas lists with short bullet points should have less leading between them. This has bugged me for ages, so I fixed it with a build-time plugin which measures the average length of a list’s items and decides how they should be vertically spaced. You can see this in action in the two lists above.

Slightly Better Callouts

I covered callouts in Moving this site to Astro but have made a couple of minor tweaks so they render more consistently in different contexts, particularly how icons are rendered.

New Fence-Based Components

Historically, the majority of fenced code blocks in my writing have contained either actual code or terminal i/o – both of which are handled perfectly by Expressive Code. But as I work more with AI tools I’m increasingly finding my code blocks contain markdown examples and file trees. While both of these are perfectly readable as plain-text code blocks, I figured I could probably do better than that.

Markdown Blocks

I’ve added a new MarkdownBlock.astro component which renders like this:

The component itself takes a markdown string, optional title and defaultView and renders both a preview of the markdown and the usual code block, with a toggle to flip between the two and a button to copy the markdown. A custom remark plugin renders this whenever I add preview to a markdown-language fenced code block and I can optionally specify a title.

```md preview title="My Preview"

I particularly like this approach because these are still fenced code blocks and will continue to render as such on platforms like GitHub.

File Trees

File trees in my content are likely to look something like this:

content/
├── articles/                              # long-form writing
│   └── 2026-05-28-work-on-this-site.mdx   # you are here
└── config.ts                              # the collection schema

When I first considered rendering these as nice HTML I looked at Starlight’s FileTree component, but it’s designed to expect a markdown ordered list and much like with markdown blocks, it’s important to me that file trees in my actual content are in tree(1) format above… because that’s how I’m likely to write them, and because they’ll still work wherever else they’re rendered.

The FileTree.astro component and its associated remark plugin work much the same as the MarkdownBlock one. A fenced code block like this:

```tree title="My Thing" {12}
content/
├── assets/                                # Assets, innit
│   ├── My Video.mp4
│   ├── pic.jpg                            # User's avatar image
│   ├── song.mp3
│   ├── data.json                          # Diagnostic data used by [Hal](https://en.wikipedia.org/wiki/HAL_9000).
│   ├── robots.txt
│   └── .config                            # Assets config file
├── articles/                              # long-form writing
│   ├── 2025-10-25-moving-to-astro.mdx
│   ├── ...
│   └── 2026-05-28-work-on-this-site.mdx   # you are here
├── notes/                                 # short-form posts and links
│   └── adding-share-features.mdx
└── config.ts                              # the collection schema
```

… will render an interactive component like this …

Some interesting points to note:

The title="" and {12} both mirror the conventions used by Expressive Code for setting a title and highlighting a line.
There’s no client-side JS here – folders collapse using plain old <details> HTML elements.
The parser is glyph-agnostic: ├──, |--, +--, tabs or spaces all parse the same way so long as they’re properly structured.
Icons are coloured by file type and # comments render as inline markdown (so links work in them).

A Fourth Typeface

When I first settled on typefaces for this site I chose Literata for articles and Jost for everything else. While I’ve always been happy with that choice for bookish prose, my choice of Jost never quite sat right with me even after switching it out for League Spartan some time ago. Eventually I realised this is because I have four distinct use cases here:

Long Form Prose. I want my essays & articles set in a distinct “bookish” serif. Literata works perfectly for this.
Code. Code examples and a few other bits should be set in a monospace font which is suited to the job. I’m still happy with Fira Code for this.
Display Type. The aesthetic of this site is inspired by early twentieth century typographic design, so a somewhat-geometric sans-serif display face is important as a design element for page headings and the like.
Other Copy & UI Stuff. Copy which doesn’t fit into any of 👆 includes the (not-long-form) prose in my notes and other pages, as well as UI controls like buttons and menus.

I’ve slowly come to realise that (3) and (4) are mutually exclusive. Any typeface that’s bold enough (and Early London Underground Vibes enough) to work as the kinda display face I want is gonna be a poor face for rendering normal copy or UI controls, and vice versa. Even worse, any typeface which kinda works for both is inevitably not good enough at either. And so after considering a whole bunch of (mostly lovely) typefaces, I went with this:

Typeface	Used for	In the wild
Geist	Display stuff	DANNY SMITH
Literata	Long-form prose	The article you’re reading rn.
Figtree	UI and short-form prose	This is a sans-serif which works great for UI stuff and also for prose.
Fira Code	Monospaced & code	`const ok = x !== y;`

This hugely improves the readability of non-bookish body copy (mainly my notes), while making stuff like headings more punchy.

Wrapping Up

Before I started on all this I took the time to rework my CSS to take advantage of all the awesome new stuff and simplify things as far as possible. This involved adopting layers, OKLCH colours, light-dark() theming and a bunch of other stuff which I may get round to writing about sometime. I also put together a proper styleguide-cum-component library to act as a reference for me when working on the design of this site. If you’re curious, the styleguide is public — though it’s really just for me.

None of this stuff is at all game-changing for the tiny number of folks who visit this site, but there’s a real joy in doing this kinda work on my own little bit of the internet.

Appending /embed to a video URL returns HTML specifically tailored for use in an iFrame – see https://v.danny.is/polite-phones-jam/embed for an example. The site also has an oEmbed endpoint and the standard video pages are set up so platforms like Notion can properly render placeholders when they are used for embedding. ↩
This is the footnote. On a page with JavaScript it expands inline, with a close button; without it, it’s just a regular jump-to-bottom link. ↩

Introducing Astro Editor

Thu, 08 Jan 2026 00:00:00 GMT

I’ve launched Astro Editor, a desktop app for authoring and editing Markdown and MDX content in local Astro Content Collections! I’m actually a bit late with this blog post since I shipped 1.0.0 six weeks ago, but hey – better late than never!

What is it?

Most Astro content collections basically comprise two things: a folder containing markdown files with their metadata as YAML frontmatter, and a Zod schema describing the structure that frontmatter should have. These content files live alongside your code.

Astro Editor provides an interface for working with these markdown files which is designed for writing not coding. The editor itself is a distractionless flow-state writing environment – it’s minimalist and gets out of your way. The frontmatter isn’t shown in the document, it appears as suitable UI components in a hideable sidebar. This shows both the frontmatter in the actual file and the available fields from the content collections schema. Here’s a screenshot of me writing this article right now.

When I dragged that screenshot into the editor it was automatically copied to the right folder in my project and renamed appropriately before the markdown image tag was inserted. I can check it’s the right one by holding ⌥ while hovering over the image tag, which shows a little preview. Astro Editor is full of little features like this, all of which are intended to let you focus on writing words without getting distracted. You can see the main features on the website (more in the userguide). Here’s a full explanation and demo:

Why?

Because I’ve wanted this myself for ages and the closest I ever got was Darkmatter – which I paid for and used regularly but never quite did what I wanted.

But why?

Most folks who publish content with Astro work in two distinct modes. We’re in coder mode when we’re editing Astro components, pages, CSS etc. This is best done in a coding tool like VSCode. We’re in writer mode when we’re writing or editing prose in markdown. Editors designed for coding are not well suited to this - they have too many distractions and lack the kinds of tools which help with writing and editing prose.

Because of this, it’s common for people to write in tools like iA Writer or Obsidian and then switch to VSCode to add frontmatter, build and publish. The workflow often looks something like this:

Create a new draft markdown file & start writing
Edit and tweak (maybe over a number of sessions)
Add frontmatter for things like description, tags etc
Build & run locally to check everything works
Push to github and deploy/publish

Steps 1-3 are very much writer mode tasks, while 4 & 5 are definitely coder mode tasks. Astro Editor is only concerned with the former which means things like:

Code blocks are not syntax highlighted because writing example code should be done in a code editor.
You can’t commit or publish because that’s best done in a code editor or terminal.
You can’t preview your writing because that’s best done in a browser while running your site on localhost.

And because the goal is simplicity when in writer mode, Astro Editor is intentionally opinionated about its UI and limits the user customisation features to “making it work with your Astro project and no more”. It’s not possible to customise colour schemes, typefaces etc.

Where we at now?

At time of writing 1.0.5 is stable for macOS and Windows and the GitHub repo has 328 stars. While I don’t collect analytics, I do get a ping whenever the auto-updater checks for a new version (which only happens automatically on launch). This includes only the currently installed version, the OS (mac or win) and a random UUID unique to each install. So I know that as of Thursday 8 January 2026:

There are 276 unique installs, 264 of which are on macOS and 12 on Windows.
Only 20 installs are pre-1.0.0
14 people opened Astro Editor today (probably, including me).

More importantly though… I’m writing in it basically every day. And I really fucking enjoy it.

So what’s Next?

Short answer: Finished Software. After years working in VC-funded startups which by definition can never be “finished”, it’s weirdly exciting to look at a 6-month-old Astro Editor and think “yeah I think it might be finished soon”.

I do still have one or two things on the roadmap though…

A complete reworking of how project config is managed, including some new options to control file naming.
Internationalization and basic RTL support.
Better quick search and internal link insertion.

And maybe better Linux support someday.

If you have an Astro site, please give Astro Editor a go. It’s only got to where it is now thanks to a bunch of folks trying it out and sharing feedback on GitHub.

And as a free open-source side project, the only marketing it’s gonna get is from people who like it saying so on their socials & websites. So tell your mates. Plz 🙏

Quite The Journey

I didn’t mean to build anything proper here. In July ’25 I was just starting to properly experiment with AI coding beyond Copilot & Cursor autocomplete and was looking for a project to use as a guinea pig. My basic requirements were:

It can’t be throwaway because learning how to hold these new AI tools properly meant more than blind vibe coding.
It can’t be a toy for the same reason.
It must be something I’ll use daily if it works because otherwise I’d not have been invested in its quality.
It must have a GUI because at the time LLMs were turbo-shit at UI design, which made this a key learning goal.
Ideally, it’s designed to run locally because any non-toy web app involves a bunch of third-party services to handle auth and emails and file storage and all the rest. Some of which cost money and all of which require me – the human – to manage them.

So I settled on iA Writer but how I want it to write my blog, which ticked all the boxes. And duly dictated some nonsense requirements into a markdown file and had cursor turn it into what I thought would be a good PRD, which became Astro Editor’s first commit.

As an AI Coding noob the maybe-kinda-working app Cursor built from this felt like magic, but after a few hours going round in circles I actually read the code and realised it was (obviously) dogshit slop. And so began the very interesting process of working out how to do that better, which I’ll write about in another article.

Fast forward a few months and I had a completely rewritten Astro Editor with a not-so-insane architecture, which both me and my new friend Claude could reason about well enough to iterate on features quickly and reliably. And on 18 Aug I shipped a feature-complete 0.1.20 and shared in the Astro Discord! 🎉

Feature complete my arse.

Turns out not everyone has the same Astro setup as me. So I spent September-November dealing with that, which involved a completely different approach to schema reading/parsing, lots of testing on weird and wonderful Astro projects and a smattering of new features.

I released 1.0.0 on 22 November 2025.

Moving this site to Astro

Sat, 25 Oct 2025 00:00:00 GMT

I started on a redesign of this site back in May 2020 after deciding I wanted a simpler, content-first statically generated site. My main goals were to keep the core as simple as possible – writing in markdown and minimal boilerplate code – while allowing me to noodle around with new-fangled CSS & web-native stuff when I want to.

After about three years running on Jekyll I started to get frustrated at some of the stuff I couldn’t do easily - primarily the difficulty of working with custom components in markdown. I was using some kinda-janky markdown pre-parsers to let me insert things like callouts…

{:.callout}
This is a callout

Which wasn’t exactly easy to work with and more importantly, if I ever decided to switch away from Jekyll and export all my markdown files, wasn’t exactly obvious or intuitive.

What I really wanted was the ability to use HTML- or React-like components in my markdown. And as with web components or react components, I wanted to define these as self-contained components with scoped CSS and the like.

So in early 2023 I started playing with AstroJS. The most appealing thing about it was the native support for MDX, its React-like component architecture where .astro files contain scoped HTML, CSS and JS, and the relatively small amount of boilerplate needed to get a blog up-and-running.

I quietly ported this site over to Astro, but with the release of Astro 3.0 in August ’23 so much had changed that it made more sense to start again from scratch. So I switched to the current codebase around the time Astro 4.0 dropped in December ’23.

Why Astro?

Modern, Simple & Content-First

Astro is very well designed, and because it’s built with a modern TypeScript-based stack, it comes with all the advantages you’d expect (typesafe javascript among them).

When used as an SSG, Astro is also very simple. File-based routing, markdown parsing and YAML frontmatter Just Work™ and stuff like image optimisation come out-of-the-box. And while composing pages from astro components feels very Reactish, it’s “zero JavaScript by default” – the generated site will only include client-side JS when necessary, which for this site is hardly ever.

Astro has an extremely strong ecosystem of plugins, tools and themes around it.

Astro Components & MDX

Components can be anything from a tiny snippet of HTML to a reusable UI component (which takes props and/or content) to a whole page layout. Here’s an example.astro component:

---
const { title } = Astro.props;
const theNumber = Math.random();
---

<section class="mything">
  <h1>{title}</h1>
  <p>Number: {theNumber}</p>
</section>
<style>
  h1 {
    color: red;
  }
</style>
<script is:inline>
  alert('Hello');
</script>

The TypeScript in the component script at the top runs only at build time. The ability to co-locate this “server-side” code with the component is useful for keeping things organised.
The component template (below the last ---) is the HTML which will be rendered when the component is used, except (much like JSX) you can use variables defined in the component script, or other Astro components imported in it.
The CSS in the style tag is scoped to this astro component only.
The script tag at the bottom uses a special astro directive, and will be executed client-side.

Building a site using Astro components is much the same as using React components (or partials in other SSGs). But the real power is using them inside Markdown Content.

MDX Components

MDX lets you use JSX inside markdown files, and is one of the main reasons I chose Astro over other SSGs. In Astro, you can import .astro components into mdx files and use them in the same way you can anywhere else. I’ve ended up with quite a lot of really simple components which just render some HTML and apply some scoped CSS to it. Here’s my highlight.astro component:

<span class="highlight"><slot /></span>

<style>
  .highlight {
    background: var(--color-highlight-bg);
    padding: 0 8px 4px;
    border-radius: 4px;
  }
</style>

And now when I’m writing in markdown I can use it like this:

Here is some text <highlight>that is highlighted</highlight>.

And with more complex components like callouts…

<Callout emoji="💡" type="blue">
  Lorem ipsum dolor sit amet consectetur adipisicing elit. Earum hic a dolorem ipsa labore cum.
</Callout>

…which renders…

The combination of Astro’s component-based architecture and components-in-MDX-files ticks some important boxes for me:

Components make for easy maintenance long term, especially when dealing with CSS.
Scoped CSS and JavaScript mean I can iterate on styles without worrying about breaking other parts of the site.
Using components in Markdown makes it extremely easy and quick to write fully featured content.
If I ever want to switch away from Astro, the structure of Astro components and how they’re used in Markdown files should make it fairly easy to port my content to another system.

So Where Am I Now?

Two years into running this site on Astro, I’ve settled into a setup that gives me everything I need without much fuss.

Content Collections

The site uses two main collections: Articles and Notes. Articles are long-form pieces like this one – they live in /writing/ and support cover images, tags, and a bunch of other metadata. Notes are shorter, usually links to interesting things I’ve found with a bit of commentary. They’re deliberately minimal: just a title, optional source URL, and publication date. Both use the same filename pattern (YYYY-MM-DD-slug.mdx) which keeps things organised and makes it dead simple to create new content.

Plugins

I’m using a handful of plugins that handle the boring stuff so I don’t have to think about it:

Expressive Code handles syntax highlighting for code blocks.
Astro Icon lets me use SVG icons without manually importing and managing them. I can just drop <Icon name="heroicons:home" /> into any component.
Sitemap generates a sitemap.xml automatically, which is one of those things that’s trivial but annoying to maintain by hand.

On the markdown processing side, I’m using a few rehype plugins:

rehype-autolink-headings adds anchor links to headings (so you can link to specific sections)
rehype-external-links automatically opens external links in new tabs
rehype-mermaid renders mermaid diagrams at build time.

I’ve also got a custom remark plugin that calculates reading time for articles.

Components

I’ve got about fifteen components in src/components/mdx/ – things like <Callout> for highlighted notes, <Accordion> for collapsible sections, <BookmarkCard> for pretty link cards, and <Notion> for embedding Notion links. Nothing fancy – just small bits of HTML with scoped styles.

The page layouts are simple – components like BaseHead, MainNavigation, and Footer get composed into layout templates like Article.astro and Note.astro, which wrap the markdown content. The whole design system is based on CSS custom properties defined in global.css, so switching between light and dark themes (or tweaking colours) is just a matter of changing a few variable values.

Future Plans

There are some notes & ideas on GitHub, but I’m not in a particular rush to ship any of it. I’d rather spend my time working on Astro Editor or using it to write stuff here.

AI and ADHD

Thu, 10 Jul 2025 00:00:00 GMT

My friend Vicki’s “mate have you considered maybe youse got ADHD” was the first time I remember this topic coming up. That was six years back and I promptly forgot about it. Then two years ago – while ADHD was all the rage on TikTok – my friend Janina had a period of revelation about herself and made me do a bunch of tests. Turns out I probably have Adult ADHD.

I’m writing this because I read a couple of posts this week which got me thinking about ADHD again, and because I’ve been knee-deep in AI-related things for the last month. The article below is a response to DHH’s rant about ADHD, which I remember skimming last year. I only just found Schneems’ response, which had me in stitches more than once…

My Red Hot ADHD Programming 'Affliction'

Sorry, Dave, ADHD is real, and (not acknowledging it) can hurt you. Hi. I’m Richard. I’m a Ruby Core Contributor. I also code in Rust, and enjoy giving talks...

schneems.com

He makes a lot of good points, but two bits cracked me up in relation to myself…

My biggest behavioral issue was that I snuck books into class and read them under my desk. If your mental picture of someone with ADHD is an out-of-control “little monster,” then this seems like the opposite. I got through college with a degree, taught myself Ruby on Rails

I also snuck books into school to read under the desk. One teacher gave me detention for it. Others brought me really interesting books from home (in one case a giant stack of New Scientist magazines), and occasionally let me get away with reading over the desk instead of doing whatever I was supposed to be doing. And like Schneems, I also got through university with a degree and taught myself Ruby on Rails.

One day, I was having an argument with my wife. It was about how I never planned dates. It got heated. She had to go to a meeting, and I planned to return to the conversation “Hey, how about we grab lunch after your meeting to talk it over.” I realized that I needed to meet the basic expectations of planning events and trying to compensate for them by taking action then and there. The suggestion might seem trite or pandering, but she thought it was good and agreed.

An hour later, she walked into my office (garage), and I literally couldn’t remember why she was there. Or rather, I was in the middle of another task, and when she walked in, I had to rack my brain to quickly retrieve the info that would provide context to her: “I’m here.” It took a split second too long, and she noticed. Turns out that I don’t “have a good memory.” What I have is the ability to recall extremely detailed information about a situation, given that I’m primed with the context.

I laughed out loud at this for like five minutes. In the two years since my friend Janina made me do those tests, we’ve laughed a lot at how differently this stuff affects each of us. The venn diagram of our symptoms barely overlaps. What Schneems describes here is not a thing for her at all, but it very much is for me. Janina and I share a house, so she’s seen (and been frustrated by) many versions of this over the years. See also my ex-girlfriends. And colleagues. And friends. Every single person I sent that quote to laughed – especially at the last two sentences.

Those last sentences are a beautifully concise version of something I’ve always struggled to articulate about myself: “What I have is the ability to recall extremely detailed information about a situation, given that I’m primed with the context.”

You and me both, Schneems. You and me both.

Entirely unrelated, I stumbled upon this wonderfully creative site:

adhdexperience.com adhdexperience.com Link may be dead

Once I’d stopped puzzling over how on earth this was built on Wix, I read the list of symptoms. It’s been two years since I read a list of ADHD symptoms and I properly chuckled at how many apply to me. I’ve circled those which I definitely experience (and I’m sure my friends would recognise) below.

Me and ADHD

When ADHD was all over TikTok, loads of friends were prodding me about getting a formal diagnosis. I didn’t seek one because knowing whether I Have ADHD or not wasn’t useful to me, and still isn’t.

Most people I know – when faced with mountains of evidence that you very obviously have ADHD – reacted with some version of “OMG this explains soooo much, this is really helpful to know”. And for most of them it’s been really fucking helpful.

My own reaction was one of mild interest. Because while “you very obviously have ADHD” was news to me, not one of the symptoms was news. I’ve always held the view that these “symptoms” were just kinda how my brain is. Sure, they make me super-shit at a bunch of things, but they also make weirdly great at other things. Whether I like it or not, they’re how my brain is. And always has been.

This muted reaction is partly because I’ve been an accidental stoic from a young age – I’ve always thought it insane to try to control the uncontrollable. Things are how they are and unless we can actually change them it’s better to embrace reality and look for what we can change. I can no more control the symptoms I circled above than I can my emotions. But I can control how I respond to them.

I realised years ago that my brain was a bit weird. I also learned that any attempt to fundamentally change it was utterly exhausting, felt turbo-shit, and – most importantly – didn’t work at all. And if I couldn’t change how my brain worked, the only sensible response was to happily accept reality, and focus on useful things I could change.

Which is why I read Getting Things Done as a weed-smoking seventeen-year-old: I had some vague notion that I couldn’t rely on my brain to stay organised. All my mates thought this was very weird. And when – like most folks who read it – I failed to stick to the “GTD Way” for more than a minute, I took the bits that actually helped me and left the rest behind. And I’ve kinda been doing that ever since.

The result is: I’m self-employed, work remotely for multiple clients and intentionally avoid anything requiring a fixed 9-5 or Mon-Fri schedule. I write everything down immediately, lest it’s gone when my mental context changes 10 seconds later. Every time-based thing goes straight in my calendar, which is always with me. I own an Apple Watch specifically to poke me when I have meetings. I’ve internalised a bunch of habits which keep my physical space tidy without any conscious mental effort. I have hard rules to avoid impulse purchases and hasty big decisions (fundamentally: “always sleep on it”). And I could go on and on…

The point is: I’ve been finding out how to work well with my own brain for decades. Far from being exhausting, the kinda stuff above is liberating when I get it right, because it feels easy for once. Figuring this stuff out, however, is often not easy. The hard work is always the figuring out, not the sustained doing. Because if sustaining a thing feels hard, I haven’t figured out the hard bit of it yet.

Whether you have ADHD or not, finding ways to work with your brain rather than against it will never be a bad thing. And after working heavily with AI for the last few months, I have some embryonic thoughts which I’ll expand on some other time.

Embryonic Thoughts on AI & ADHD

In no particular order, some embryonic thoughts on AI, me, and possibly ADHD…

1️⃣ A Focussed Context Window (for me, not the LLM)

When most folks get a WhatsApp message asking if they’re free on such-and-such date they’ll open their calendar app and either reply with an alternative date or add an event to their calendar, before closing it and carrying on with whatever they were doing before.

When I get a message, 50% likely to do exactly this. But in the other 50% I’ll catch sight of some unrelated meeting or event next week and my brain will instantly switch context to thinking about that. Worst case, this means I forget to deal with the message which caused me to open my calendar in the first place. Best case it takes 15 minutes to refocus my brain on whatever I was doing before.

And this applies to loads of shit. It’s why I check email at designated times and why none of my tech sends me notifications. This problem is easily solvable by deliberatly doing One Thing At A Time in an isolated context. Right now I’m writing this post in a super-zen minimalist editor precisely so I don’t get distracted.

But that’s not how most knowledge work works. Most work constantly requires context and information from places other than where we’re currently working – calendar, meeting notes, slack, notion, the web, etc etc etc etc.

So the real challenge for me here is creating an environment where I always have the full context I need for what I’m doing right now but nothing more.

While I can kinda do this manually it takes way more energy than it does for most folks, so I’m particularly excited about the potential for AI tools to help with this. Which is kinda amusing because – like me – LLMs also operate best when their context window contains exactly the right stuff.

2️⃣ Meetings Etc

Meeting recording and transcription tools are a big deal. For most of my life I’ve waged an internal battle between losing myself in the experience of a good meeting and ensuring something useful comes out of it after. Whether I’m stream-of-consciousness jabbering while excitedly hand-waving or listening rapt while others do so, I’m concious that creating & guiding effective conversation – and capturing the useful bits of it – requires skilled facilitation. I often end up in that role, requiring a decision on whether I want to do it well or fully participate in the conversation. Because I absolutely cannot do justice to both at the same time.

AI cannot ever replace skilled human facilitators. But in the (many) situations where my de facto facilitation role is just preventing unhelpful tangents and ensuring we remember the important bits after… AI can totally take the latter away from me during the meeting itself.

Paired with vaguely sensible meeting practices, AI tools like Notion’s meeting recorder have really helped me to stay present and focussed during calls.

3️⃣ Faster Side Quests

I’m certain there’s a subreddit dedicated to the partners of ADHDish people sharing funny-but-exasperated stories about this afternoon’s progression from quickly cleaning the garage to driving forty miles for a custom-machined nozzle for the tool that oils the leaf blower while the contents of the garage remains 50% organised and labelled in excruciating detail and 50% definitely not going back in the garage before nightfall.

I’m like this, and I fucking love it. I love that custom-machined nozzle and its metaphorical brothers. I could legitimately argue that my whole career has been a series of semi-random side-quests stacked on top of each other.

I’m lucky that given enough time I’m pretty good at working back up the chain of side-quests until eventually the garage ends up clean. But that often takes a bit too long, and I run out of time, and the stuff on the drive gets nicked or rained on otherwise ruined. If only today was longer and I had a floodlight etc.

LLMs won’t help me with my garage, but they can make a lot of computer-based side-quests waaaaaay faster. More importantly, they significantly reduce the time between me embarking on a side-quest and realising either A) it’s more than a side-quest and I should treat it as such or B) it’s not worth persuing. I’m talking weeks to hours in some cases.

TL;DR: LLMs have allowed me to follow side-on-side-on-side-quests and come back up the callback chain in a reasonable timeframe way more than I could before. Which is both fun and useful.

4️⃣ Context Switching When Bored

I get bored way to easily. But I also hyperfocus easily. I’m lucky enough that I’ve worked out how to blend those things into something which makes me good at learning things and doing things.

A large part of that is my ability to maintain focus on things in a macro sense over periods of time. But the one thing I cannot fucking do is maintain focus in a micro-sense when it’s gone. In the course of writing this article I’ve walked downstairs six times to smoke a cigarette and twice to make a cup of tea. I’ve folded five T-Shirts, weighed myself and noted the result in my journal and resisted countless urges to open a web browser.

None of those things took more than 5 minutes and none distracted my macro-brain from this article. But without them I’d have been impotently raging at my keyboard.

Because while I need that focused context window in a macro-sense, I need regular mini-distractions in the micro sense.

Surprisingly, I’ve found that doing at most two things at once with agentic AI tools ticks this box. I legit smoke fewer cigarettes when working on two unrelated tasks using AI agents. When I need a break from hard thinking about Thing A, I set an agent off doing something useful on it and context switch to checking in on what AI has done on Thing B. Prodding Thing B’s AI towards the next thing is just enough of a break to bring my brain back to Thing A. 🔄.

This only seems to work if Things A & B are not the same complexity. AI coding agents (in Aug 2025) don’t have sufficiently nuanced mental models to make non-trivial decisions about software engineering – nuanced mental models is my job as the human overseer. But if I’m doing that for Thing A, I need Thing B to need the same nuanced mental models I’d give to smoking a cigarette or making a cuppa.

When this works, context switching between two tasks improves my ability to focus on both. Which is new to me (despite many attempts to kid myself otherwise in the past).

Wrapping up…

Writing this has been weirdly cathartic because it’s the first time I’ve properly ordered any thoughts about this stuff. But also because whether we’re talking about AI or our own brains my parting message is the same…

This is what it is, and pretending otherwise is foolish. Our job is to work out how to use it in a way that’s positive for both ourselves and the wider world.

I don’t think AI will ever be better at 👆 than humans. Solong as we give it the time of day.

Personal CRMs Aren't What I Need

Mon, 05 Feb 2024 00:00:00 GMT

I paid a 12-month subscription for a Personal CRM called Clay because I need help “managing my personal and professional relationships”. It’s not bad software. BUT…

It turns out what I need is not Clay, or any other “Personal CRM” I’ve found.

It feels like most of these Personal CRMs are made by folks with very different problems to me.

I know a lot of founders, execs, freelancers (and salespeople) who are very good at building and maintaining their personal relationships… it’s a huge part of their job after all. Most of them reach out to people, meet new people and get/make a lot of useful intros on a daily basis.

For them, Clay’s features are probably pretty useful. I can imagine it’s useful knowing it’s Andy’s birthday today, and when you last spoke 9 months Andy was struggling with X, Y and Z and had a baby due in August. And that Andy’s job on LinkedIn changed 3 months ago. Etc. Because all that makes excellent context for a quick email to reopen a conversation.

If you read that and thought “well duuh what’s a CRM for?” you’re one of the founders/execs/freelancers/salespeople I’m talking about 👆. We probably agree that the job of a personal CRM is keeping information about the people you know organised, current and readily available.

Which is exactly what all CRMs are for… sales CRMs were originally designed to help salespeople manage exactly this kind of information in a sane way, making it easier to maintain meaningful contextual relationships with customers & leads.

But that’s not at all what I need from a “Personal CRM”. If it was I’d happily be using a janky setup of Hubspot, Zoho, Salesforce (💸) or similar to manage my personal relationships.

What I need is a tool that solves a different set of problems. I need a tool that makes maintaining and growing my personal relationships & network easy and fun. I need a tool for people who are not good at this stuff in the first place.

I need a tool that pings me before I meet someone new and suggests context-aware questions & conversation points. I need a frictionless way to note the important bits down and resurface them appropriately. I need to know when two of my contacts have something non-obvious in common, and an easy way to intro them. I need to be magically reminded that when I last spoke to Anna from Random Startup Ltd she was excited about her family trip to Croatia, and I want that reminder (with context) 3 days after she gets home – or when I happen to end up in Croatia myself.

When I meet people in real life I invariably have a million great conversations, intro people all over the place and get excited. I am by no means bad at building genuine relationships. I need a tool that helps me feel like that when I’m sat at my desk.

Most of all, I need a “Personal CRM” which solves an unsolved problem for me…

I need a tool that makes managing my network of personal relationships feel like the opposite of what salespeople use CRMs for.

I have a large extended network of people with whom I have potential mutually meaningful relationships. In sales parlance, they’re almost all “very warm”. But for the most part, none of us is trying to sell shit to each other. In common with a lot of other people in that network, I’m crap at maintaining the relationships that constitute it and even crappier at cultivating the second-order relationships that could expand it.

I need tooling to help me with that.

Since we’re discussing Personal CRMs, here’s a not-at-all-work-related take…

My housemate is amazing at maintaining her myriad personal relationships. Nothing to do with her work. She loves buying super-thoughtful presents for people she barely knows. She always remembers to invite randos from the pub to stuff they’d enjoy. She always remembers to message about important stuff in folks’ lives. And very quickly “barely knows” doesn’t apply. This is genuine relationship building done well.

Meanwhile I’m the opposite (I’d forget my own birthday if said housemate didn’t remind me). Sure, I could learn to behave like her, but it would never be natural and I’d never get off on it the same way she does.

It feels like every Personal CRM I’ve seen is designed for people like my housemate, or even worse… the I-Am-At-Work equivalent of her. ie. Folks who enjoy and are somewhat good at this stuff.

Perhaps obviously, it also feels like every Personal CRM I’ve seen designed by this kind of person.

And it feels like for this kind of person the core value prop of a “Personal CRM” has already been solved by CRMs in general. (Every good salesperson I know maintains a personal CRM of sorts… none use a specific Personal CRM tool.)

It feels like at best, a Personal CRM is slightly tweaked UX presented as a skin over an already-solved problem.

Meanwhile the problems I have are mostly unsolved by software. I signed up for Clay because I need help “managing my personal and professional relationships”. But what I need is not a tool like Clay. Because everything I said above.

And I’m convinced I’m not alone here. I know too many people like me who are excellent at building deep, meaningful relationships with a few people, but can’t bridge the gap to doing so more widely.

I’m equally convinced that none of us is likely to found a “Personal CRM” startup to address this.

But my goodness would we throw money at someone who did.

Does this chime with anyone else? 👆

PS. I’d love to see Clay’s churn data, segmented by a yes/no to “Do you enjoy buying gifts & organising birthday parties, and when you have amazing convos with people at conferences, do you message them afterwards?” Then label with potential high-value customer.

EDIT: Practical Example…

I bumped into Chase Warrington a bit ago. I’ve been a fan of Chase’s work for ages, and very much look up to him in a work context. He’s exactly the kind of person that should see me stuffing everything I know about him into my “Personal CRM” so I can extract the maximum value from our relationship.

But that’d be mental because neither of us are arseholes, we’ve got nothing to sell each other and fuck basing any relationship on the extraction of value.

I want a Personal CRM that’s like “Chase just interviewed someone you know on his podcast, you should listen to that one and then maybe WhatsApp them both?” or “Chase is in London right now and he’d definitely like this band you’re going to see tomorrow but FYI he’s here for a funeral”.

Building Healthy Remote Organizations - The Silent Enabler of Success

Thu, 10 Feb 2022 00:00:00 GMT

For a long time I’ve believed that organisational health is a hugely undervalued ingredient for success – especially for startups that are scaling fast. It’s the silent enabler of so much else. Before I give you my take on it, here’s a succinct definition of Organisational Health…

An organization’s ability to function effectively, to cope adequately, to change appropriately, and to grow from within.

For me it’s about intentionally creating a resilient, cohesive organisation that can operate with a sustained sense of calm.

Really healthy organisations tend to feel calm even when they’re ploughing through unknown waters at a thousand miles per hour. They’re able to operate on the edge of chaos without becoming chaotic.

Despite the obvious benefits of a healthy organisation, it’s often neglected – I think for a few reasons…

It seems kinda boring – we’re conditioned to believe the best solutions come from fancy, innovative approaches. Being healthy isn’t complex or innovative… but it does takes sustained effort. And there’s none of the adrenaline which usually comes with startup leadership.
It’s very hard to quantify results. The best measurements of organisational health are whatever we use to measure general success (growth, revenue etc) but this makes it very hard to measure the effect of work. As always, useful proxy metrics are hard to find.
It needs a holistic approach - it cuts across leadership, operations and people functions, as well as every other function in a business. Which makes it hard.
Founders are often unskilled in this domain – the skills needed to grow a healthy organisation often feel quite at odds with the other skills required to be a good founder. (Some only realise this when the wheels fall off but I’ve met a lot who realised from the start, felt horribly inadequate as leaders and stuck their heads in the sand.)

Remote and distributed companies need to be much healthier than office-based firms because co-location allows us to paper over an awful lot of cracks. And systemic health problems have a disproportionately large effect on remote teams, which quickly compounds with scale.

So what does a healthy organisation look like to me?

These kinds of things…

Happy, autonomous and empowered people (obviously).
A unified, coherent senior leadership team exhibiting all the traits & behaviours we’d expect of any other great team.
Common, well-understood shared norms, habits, behaviours & ways of working. (We could label this “culture”.)
Common, well-understood values and principles which facilitate aligned independent decision-making at all levels.
A clear, truthful and well-understood structure (org design, teams, career levels, salaries etc).
Excellent communication everywhere.
A culture that values clarity.
A culture of trust and psychological safety.
A culture that cares about how we work, and actively tries to make it better.
Systems, processes and tools that make it easy to “operationalise” repetitive work.
Managers who have the time, skill and motivation to lead and manage well.

None of these things happen by accident.

So when should you start thinking about organisational health?

Short answer: as soon as you reasonably can.

Small, young companies get disproportionally large gains from the effort, which compound over time. Without the right foundations this all gets exponentially harder as you scale (and as your collective habits and ways of working become entrenched). I’ve seen way too many companies ignore this stuff until they’ve raised a Series B and the wheels start falling off.

Having the foundations for a super healthy organisation allow you to scale quickly without as much pain, and help things stay calm as the organisation rapidly becomes more complex.

So how do we start getting healthier? 🌱

Firstly, we need to believe it’s at least as important as our other business aims. Being healthy is unlikely to be the number one goal but, as with human health, unless we make a strong commitment to it, it’ll always lose out to other more pressing stuff.

Secondly, we need at least one person who’s wholly focussed on keeping our organisation healthy. I’ve seen some amazing small startups where this is the fundamental job of the COO. More recently, I’ve seen this owned by a Head of Remote.

In larger firms I’ve seen teams called Workplace Design, Office of the COO, Remote Operations, People Operations, (plain old) Operations, and the like. The one thing these have in common is that they are 100% focussed on making the company itself as healthy as possible.

Ultimately, keeping an organisation healthy will always be a joint effort led by people like…

COO, VP Ops etc
CPO, VP People etc
Chief of Staff, Head of Remote etc
Leaders specific to the company’s core business (eg CTO for tech companies)

None of this happens by accident.

Guiding Principles 📜

Here are a few loose principles I’ve found useful for helping folks approach organisational health. (I could – and probably will – write a whole article on each of them.)

1️⃣ Have an internal focus

Most functions in a startup are led by external needs & drivers: Product, Engineering, Sales, Marketing, Strategy, etc… all should have their eyes set mostly on the outside world.

We need at least one function which has an internal focus, treats the company like a product, itself as a product team and its employees as users. And this function needs a good product manager.

Done well, this function is a huge force multiplier for all the others.

“We design how our company works as thoughtfully as our products.”

2️⃣ Beware organisational debt

Just like a software product accrues technical debt, a company accrues organisational debt. The effects are similar - it gets increasingly harder to get stuff done over time.

Used strategically, this kind of debt is useful because it lets us move faster, but the tweet below explains why we must be intentional about how we incur it. And how we pay it down.

The opposite of technical debt isn't zero debt, it's compounding gains: each new thing makes it easier and faster to build new things.
— Matt Wensing 🐙 (@mattwensing)
June 10, 2020

3️⃣ Human + System

These are the two fundamental components, and Internal Operations should focus on both:

Human - Relationships, culture, leadership, human growth, shared mindset, “vibes” etc.
System - Structure, process, policy, tooling, automation etc.

These need to be viewed and tackled together and the highest leverage stuff addresses both human & system concerns at the same time (eg. shared behaviours & habits).

4️⃣ Behaviours & habits over processes & tools

While processes and tools are important, the most effective way to improve an organisation’s health is by improving the habits and default behaviours of its people.

If you’ve ever tried to impose a new system or process without considering behavioural change, you’ve probably seen a lot of folks ignore it and revert to what they know. People always fall back on their habits and default behaviours. Especially in groups.

On the plus side, given the right habits, behaviours, principles, environment etc, people will likely create effective systems & tools on their own.

That said… used intentionally, processes and tools can be very powerful tools for affecting behaviour & habits. Especially in groups.

5️⃣ Strive for clarity

A culture of clarity reduces day-to-day uncertainty and tends plenty of efficiency savings (especially in distributed companies). But its greatest value comes from how it reduces the cognitive load on people.

At best, lack of clarity leads to increased cognitive load as folks struggle to make sense of things and make decisions themselves. At worst, it leads to a culture of uncertainty and stress because in the absence of facts people always assume the worst. In either case, it means people are spending a lot of time thinking and talking about unnecessary stuff.

Creating clarity in a complex and inherently unclear environment is one of the hardest things about leadership, so leaders often think about clarity in a very macro sense: is everyone clear on our mission? Or our Q3 goals?

Yet most of the uncertainty, inefficiency & stress I’ve seen comes from lack of clarity on tiny things:

I’ve found five different versions of this template and have two conflicting answers about which one to use here.
What’s this meeting about? I don’t really know what’s expected of me and what are these weird notes I’ve been sent all about?
Is it okay to expense my new headphones? How do I do that? Who do I even ask?
Who should I talk to on the marketing team about this thing? Misha told me Andy, but which Andy? He’s not on the org chart? Wait, is Marketing even the right team?

Creating clarity & consistency on stuff like this is often much harder than it seems – especially in large, fast-growing or globally distributed companies. But done right, it can have an insanely big effect on organisational health.

6️⃣ Practice simplicity

Simplicity matters because simple things are easy for people to fully understand and reason about. When designing systems we have to consider the usefulness and accuracy of the mental models folks form about them.

It’s much easier to augment folks’ existing correct mental models than to fix their incorrect ones.

A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system. — John Gall (1975, p.71)

Designing simple solutions for complicated problems is almost never simple itself, but wherever possible we should aggressively err on the side of simplicity.

7️⃣ Harness the power of principles

Principles are often more useful than rigid rules because when they’re fully understood they allow people to confidently make decisions without constant recourse to others. They also help people understand the why.

Even when you need rigid rules, clearly explaining the principles which underpin them increases transparency & shared understanding, and helps folks to adapt the rules intelligently.

For any principles to be useful they need to be well-thought-out, easy to understand and constantly reinforced by everyone. Otherwise, they’re just more words in a document somewhere.

8️⃣ Create frameworks (as well as tools)

Our inwards-facing function needs to build an environment & toolset that helps other functions do their best work. But also go one step further and create the environment & meta-tools that allow others to design their own.

We can’t design an entire company from the top. Nor can we design by general consensus on everything. Instead, we need to provide a framework of strong, consistent guide-rails (principles, tools, practices, structures etc) that everyone trusts.

This is the kernel of our “Operating System”. If everyone really understands this framework and buys into it, (with a little help) they’ll be able to create their own systems of work on top of it. And our kernel helps keep those systems compatible with each other.

Doing this is the only real way to create a truly agile organisation that can evolve as it scales.

Of course, keeping the kernel fit for purpose takes ongoing effort. As does guiding and nurturing the people and systems that use it.

These are just a few of my thoughts on what it takes to keep an organisation healthy, but hopefully they’ve sparked a few thoughts for you.

If you take one thing away from this, let it be the idea that creating a great company only happens when we set out to do so with intentionally, and when we get it right the sense of calm it can provide is a silent enabler of so much else.

And with many of us moving towards remote, globally distributed organisations, all this matters much more.

Website Redesign Part XVI - A Header and Footer for Articles

Sat, 29 Aug 2020 00:00:00 GMT

I pretty much finished designing the article pages back in Part XI, and after deciding on a typeface and some general design rules for the rest of the site it’s time to finish it off by adding a header and footer to the article pages.

The Article Header

Here are a few ideas I played around with for the header.

Although I quite like some of these, it feels like I’m overcomplicating things a bit. It might be better to go with something really simple for now – just a link back to the homepage in the top left corner.

The Article Footer

The footer needs to include some links, my name and a copyright notice. After a little playing about I ended up with something like this…

While I like this, it needs more thought to make in work well on small screens, and I’ll be a challenge to implement without overcomplicating the code because of how I’ve set up the article CSS. So much like the header, I think it makes more sense to keep things simple and just provide a link to the articles index, rather than listing related/recent articles. I expect I’ll revisit this in the future.

The Code

Here’s what I ended up with for the CSS…

There’s definitely some scope to simplify this, and to add some more “features” to the footer, but this feels like it’s enough to call the articles done and move on to the rest of the site.

Auto Generating Jekyll Posts that Redirect to Medium

Thu, 13 Aug 2020 00:00:00 GMT

I’m making quite heavy use of the jekyll-redirect-from plugin. This allows me to create a normal apge or post file with a special frontmatter item and have the page 301 redirect to the specified URL. I’m already using this to forward URLs like <danny.is/using> to Notion, but I also want to use it for blog posts that I’ve written elsewhere.

I’ve recently written an article for Delocate, and I can quickly add that to this site by creating a file in _posts called 2020-07-31-not-all-comms-needs-a-purpose.md with the following frontmatter.

title: Not all communication needs a definite purpose
redirectURL: 'https://www.delocate.co/blog/not-all-communication-needs-a-definite-purpose'
platform: delocate

The post will behave totally normally as far as Jekyll is concerned, but instead of rendering the empty body, it will 301 redirect to the specified URL.

Although I’d like to move all my medium posts over to this site in the end, that’s a big job. So for now I want to create a file like this for every medium post I’ve written. Creating 40 of these files by hand isn’t very appealing, so I whipped up a quick ruby script to do it for me.

I started out trying to parse medium’s RSS feed but it doesn’t include all the posts, so I’m using medium’s private API instead. The script hits the medium API, extracts the data I need into an array and then loops over it creating a correctly formatted file for each post. It lives in scripts so I can run it whenever I want with ruby ./scriipts/generate_medium_forwards.rb to pull any new medium articles in.(If the whole Medium class seems like overkill, it’s because I based this on some old code that was more reusable.) Here’s the code…

This worked a treat and I only had one hiccup: I spend far too long trying to work out why many of the articles had identical published_at dates before I eventually realised that I needed the firstPublishedAt value rather than the publishedAt one – the latter gets updated every time the post is edited and re-published.

Website Redesign Part XV - A typographic system for the rest of this site

Wed, 12 Aug 2020 00:00:00 GMT

When I started this redesign I already had a fairly clear idea of the aesthetic I wanted, based on the existing design. These two pages show that off quite well.

I’m not sure where I got this aesthetic from, but it’s clearly draws on the work of Jan Tschichold. Jan was a typographer and designer who’s famous for a whole load of stuff (go read his Wikipedia page). I particularly like this style, which is closely associated with him.

I spent quite a while trying to establish some sort of typographic hierarchy for the rest of the site based partly on some thoughts from my last article. Eventually I realised that this is really hard when I’m going for a deliberately “whacky” aesthetic. The kind of style I’m after doesn’t lend itself well to rigid hierarchy. And the fact I’m likely to size some type with viewport units makes this approach even less sensible.

So I went back to square one and decided on a few guidelines and constraints in place of a hierarchy:

Use type and layout over imagery and effects.
The site should always look good in greyscale. While I can use colour, it should never be the main design element.
One typeface only, but I can use it in any weight or size that feels right.
Always consider visual hierarchy, and be consistent across pages where possible.
A grid of 20px, but with permission to ignore wherever it makes sense.

I also settled on a modular component-based approach where possible, and identified a few core components that will be useful in all sorts of contexts going forward. They’re deliberately simple and extensible in their design.

Deciding on a typeface

I spent way too long choosing a typeface for articles, so I’m keeping the simple. I decided to stick with Futura PT. It works perfectly for the look I’m going for and looks good in all caps, which I’ll probably be using a lot. This choice has some downsides though: the biggest being that it’s not available for free so I’d have to keep my Adobe Fonts license and accept the dependancy on Adobe’s service.

I’d pretty much decided to suck that up when I discovered Jost*. It’s a pretty close match for Futura, is open source and available as a variable font. It’s slightly larger than Futura but after a bit of trial and error I think it’s a good trade-off.

Text Styles & Components

With that decision made, I threw together a few basic components and text styles in Figma. there’s no real system for this – I started with the components, extracted text styles from them and then did my best to consolidate them a bit.

Having these styles and components is a great starting point for some experimentation. I’m gonna hold off coding them up until I’ve done a few iterations in Figma – I’m sure they’ll change a little bit as I play with them. The only technical work I’ve done is to build Jost’s variable version from source and bring it into my site.

Website Redesign Part XIII - Taking Stock of Content

Sun, 12 Jul 2020 00:00:00 GMT

I’m now pretty happy with how the essays on here look, so it’s time to turn my attention to the rest of the site. Although I have an idea of the aesthetic I’m after, every time I’ve opened Figma to have a play I’ve found myself staring at a blank page wrought with indecision – the dreaded writers block. Or rather, designers block.

I didn’t feel this at all when designing the essay pages because I had a clear idea of what I was trying to do. I already had content to work with and my only job was to make it as readable and beautiful as possible while keeping things simple. Clear goal. Clear starting point.

But with the rest of the site it’s not so clear. In Part IV I identified a list of pages I need to design, and I did some high-level pondering on goals and user needs in Part II. But beyond that, I’ve basically got no constrains and no starting point. And it’s paralysing me.

Back when I made websites for a living, the first thing I’d look at after user goals was a content audit. If the client didn’t have any existing content to audit, we’d focus on the content they thought they were going to have. So that’s just what I’m going to do now.

A Content audit for this site

I can think of a hundred other things I might want to put here someday, but that’s all the stuff I’m thinking about putting here right now.

Organising the post-its

Let’s take a stab at organising these post-its according to a few different taxonomies. This might seem like overkill for such a small set of content but this exercise often throws up unexpected and creative ideas for organising and grouping. Even if we don’t use them, they can help seed concepts we use elsewhere.

By type

Let’s start with the most obvious, grouping by content type – the first word of each post-it is a good starting point. We could also group by whether the content is mostly writing (yellow) or mostly something else (orange).

By author

I’ve been thinking a lot about the creation and consumption of information lately, so it’s not surprising this springs to mind as a possible grouping: did I create it, or did I consume it? Some stuff is hard to categorise here – a book recommendation is clearly consumption, but what if I add my own review?

By professional or personal

Since this is a personal site, we could consider grouping the content by whether or not it’s related to my work.

It’s pretty obvious that most of the content types here are focussed on my work. Looking at the both pile, the vast majority of content represented by each post-it is work-oriented. (While I do read some non-work articles via pocket, they’re in the minority. Likewise for articles on this site. Etc.)

So this grouping doesn’t feel very useful. Moreover, it doesn’t feel authentic – I’ve always mixed work and play and I’m not really sure where the line between them is. That solitary orange sticky note makes me question whether my music videos belong on this site, though.

By Importance

Some of these post-its are more important to me than others. My writing – whether on this site or elsewhere – is pretty core. As are links to my series’ on Notion. But the books I’m reading are much less important – I could live without having them on this site at all.

Perhaps the design should emphasise the important and de-emphasise the less-important? Or perhaps the less-important shouldn’t live here at all? My view of what’s important is almost certain to change over time, so if I do emphasise some content based on this it should be easy to change.

By Permanence

One of the main reasons I’m moving my writing to my own blog is permanence. I don’t like the fact that Medium controls my content and URLs. I want a more permanent place to put my words. Somewhere they can live forever – etched in stone, as it were.

The same is not true for other types of content. My tweets are ephemeral, for example: I wouldn’t be overly bothered if they all disappeared one day. Perhaps we could try grouping along these lines – stuff that I care about keeping vs stuff that I don’t.

But what about the actual content?

If you’ve ever done any information architecture you’re probably shouting at your screen right now…

BUT YOU HAVEN’T CONSIDERED ANY ACTUAL CONTENT! It doesn’t make sense to group based solely on medium.

You’ve got a point.

It’s kind of ridiculous to go through this exercise based only on the medium in which the content exists. We should also be considering things like subject area, target audience and purpose. For large sets of information these things will probably suggest much more useful taxonomies than content type.

I’ve ignored these so far because I don’t want to base the structure or conceptual design of this site on the topics I’m currently engaging with. I know too well how quickly they can change, and it’s important this site can adapt to those changes without much effort on my part.

Having said that, I’d be foolish not to at least consider the kind of content I’m producing right now. For the past few years, my interests – and especially the stuff I write about –have fallen in one of four loose categories.

I’ve started to loosely group these into two super-categories: Human and Systems. The first includes everything where an actual human is the focus – think coaching, mentoring, nurturing etc. The second is focussed on the environment in which humans operate and how it can be engineered to provide the most useful support. I’ve been doing a lot of gardening during lockdown, so if you’ll excuse the metaphor…

Caring for a garden requires system design and engineering. Plants need the right soil, pots and sunlight. Some need the support of a rigid framework like a trellis. Growing from seed often means adherence to a thoroughly-researched process of feeding and repotting. But on its own, this stuff can’t possibly create a beautiful, thriving garden. Plants need to be nurtured and guided, and they won’t always do what we expect. As gardeners, we must observe individual plants and do what’s best for them, using our intuition and experience to guide us.

A creeper might grow without a trellis, but it will be in a random direction and will have to work much harder to get up the wall. But a trellis is useless without daily watering and occasionally guidance. And sometimes a creeper will ignore the trellis and decide to weave beautifully around a fence instead. It’s up to us to notice where it’s heading and either correct or encourage it. And perhaps remove the trellis, if it’s not proving useful.

Like creepers, people need trellis’. They’re the systems, habits, processes and frameworks that support us and make our lives easier.

We also need nurturing and the freedom to explore our own path. If we have good gardeners looking after us, we can rely on them to guide and prune as needed, and to move or replace the trellis when it isn’t helping.

The more I reflect, the more sense these two categories make to me. Both Human and Systems work need to be in balance, and my interests can be sorted fairly well into those two buckets. (It’s interesting that the least happy bits of my career have occurred when I’ve been too focussed on one or the other)

I’ll explore this idea further outside the context of this redesign, but it provides a reasonable starting point for a top-level grouping of my content.

How is all this useful?

What can we take from all this, and does any of it help with my designers block? This process has certainly sparked a few interesting thoughts which I’ll definitely come back to in the future. It’s also sparked a few that are useful now.

Grouping by type provides a good indication of the components I should think about (Link, Video, Book, Page, Article, Other), but is not useful as a way of actually organising content.

Grouping by author raises the possibility of subtly differentiating content I’ve created from content I’ve consumed/curated. I’m not sure how useful this distinction will be for readers, but it still appeals to me as something to consider.

Grouping by professional/personal isn’t really useful, though perhaps my music doesn’t belong on this site and I should just link to youtube.

Grouping by importance raises the need for flexibility. I need way of focusing attention on stuff that’s important to me right now, knowing it might change over time. This might be as simple as moving stuff that’s currently important to the top of some list, but this has design implications. It should be easy for me to promote/highlight different types of content as my needs change.

Grouping by permanence doesn’t feel very useful at all.

Grouping by Human/System, and by the four categories of content feels like a good starting point for some labelling system which I should explore further.

Keeping it simple

Simplicity is a the core value of this redesign and working through this process has helped me reach a few decisions about how to simplify things.

I’ve no need for a coaching page right now. I can add this in the future.
I still want a hire me page but it makes much more sense for this to live in notion. I’ll forward https://danny.is/lookingforwork and https://danny.is/hireme to a public Notion page and be done with it.
I won’t show any actual videos on my site. Instead, I’ll present any video series’ as links to notion pages or YouTube playlists. I already have these set up.
I won’t have a page for my music. I’ll just forward https://danny.is/singing to my dormant youtube channel. I will show this link on the homepage, though – singing is a big part of who I am.
I won’t worry about notes for the moment¹. They’re an important part of how I’d like to share content but aren’t a priority and Notion might well be the best place for them.
I don’t care about books at all right now. If I really want to write a book review I can just write an article.
Core design concepts should be expandable to accommodate the unknown. For example, these would be bad ideas:
- Deciding I have three main types of content and basing my entire design concept on “threes”.
- Having all my videos on youtube and Loom, and using their brand colours as core design elements.

Wrapping up

I started this article as a way to get over writer’s block, hoping that a content audit would help provide a few constraints and possible design directions. It’s been an interesting little exercise and has definitely helped unblock me, but when I think about it all I’ve really done is intentionally focus my attention the same problem I had in the first place: what should I have on this site and how should I organise it?. So while this “content audit” was interesting, its real value came from forcing me to consider this problem in a structured, systematic way.

If you’re wondering what I mean by notes, I used to use tumblr for this sort of thing. ↩

Website Redesign Part XIV - Stepping Into Figma

Sun, 12 Jul 2020 00:00:00 GMT

Figma is one of my new favourite tools. I’ve been an avid fan of Sketch since I first picked it up in 2011. Compared to the other tools available at the time, it was a breath of fresh air. I still remember how excited I felt after I first used it for some actual work.

The first time I used Figma I had a similar feeling. Everything was just easy. Coming from Sketch, Figma felt comfortable and a lot of the keyboard shortcuts are the same so no need to reconfigure my finger-memory. Figma has some major advantages over Sketch. It’s web-based so it runs on any machine with a browser and my files live in the cloud by default. Anything I can do to simplify my laptop’s setup is a win for me. It also has great multiplayer – working collaboratively is an absolute joy. And it feels simpler than Sketch. The interface feels more intuitive and the way it handles components feels way more natural. So I’m now using Figma for pretty much all my design work.

Until now, I’ve been designing this site in the browser and haven’t felt the need for a design tool. But now I’m getting to the rest of the site, I know I’ll want to experiment with layout and colour faster than CSS allows. I also want to explore Figma’s component and shared styles features and this feels like a good excuse.

Text Styles

We can recreate the styles for these essays pretty easily. If we assume 16px as our base font size, it’s just a matter of doing some maths based on the em values in our CSS to get the size and line-height of all our text styles. Figma also lets us control some of the more advanced font features we’ve been using in our CSS.

With very little work, we can create a styleguide and create corresponding text styles. Here’s what I ended up with.

Colour Styles

While I haven’t given much thought to colour there are a few colours that I’m using in the CSS, so it makes sense to create some named colour styles and a palette in Figma too.

Grids

Since the line-height for my essays is 1.5, the baseline grid is 24. I use this measurement quite a lot in the CSS already, both for horizontal and vertical spacing. Figma allows us to create grid styles which we can apply to frames. Let’s create a simple grid style for 24px, and use it to position some content on the grid.

We can also create a grid that represents one line-height’s worth of padding around a frame, like this.

The trick is to create two grids, one Rows and one Columns, both with the same settings:

Count: 1
Type: Stretch
Margin: 24 (your desired padding)
Gutter: 0

Then we can combine both grids by creating a Grid Style that includes them both. And voila, we have a grid that we can apply to any frame to give us the correct guides for padding.

Components

Before we can call this minimalist design system done, we need to account for a couple of components that we can’t create using text styles alone: code blocks, blockquotes, lists and horizontal rules. We’ll create these as components, using the text and colour styles we’ve already defined. By using constraints we can ensure the content adapts properly as component instances are resized. Here’s what I ended up with.

Summary

None of this is especially useful right now, but it’s provided a starting point from which to design the rest of the site and taught me a few things I didn’t know about Figma.

Website Redesign Part XII - Responsive Images

Wed, 01 Jul 2020 00:00:00 GMT

The last time I built a content-heavy website, responsive images weren’t really a thing. In fact they were a definite problem for most developers. We could control the visual size of an image with percentage widths and media queries, but we had no easy way of controlling the actual image used by the browser. The easiest thing to do was just supply a very big high-res image that would look good on wide viewports and accept that smaller viewport devices would end up downloading a file with more detail than they could use.

The last time I gave any real attention to this problem I was working on a site with a lot of high-res background images. I dealt with it in three ways. Firstly, I used a jpeg that was too big for even the largest viewport, but with JPEG compression turned all the way up. This was then scaled down with CSS. This actually reduced the file size, and generally looked pretty good – even on new-fangled retina screens¹.

Secondly, I spent ages blurring parts of the image in photoshop. The idea was that the fewer individual colours there were in the JPEG, the smaller the filesize. Take a look at this photo:

There are probably hundreds of different shades of blue and grey in the sky, each one taking up bytes in the JPEG. By blurring the sky as much as possible, we end up with far fewer shades of blue and so reduce the filesize. Doing this was a pain in the arse.

All the other stuff involved swapping out images with javascript.

Thankfully that was ages ago, and we now have some much better ways of handling responsive images. Both secret and the <picture> element were being talked about when I stopped making websites for a living, but both are now well-supported by modern browsers.

SRCSET

The srcset attribute allows us to specify different image files to use at different resolutions and viewport widths. It looks like this.

<img src="small.png" alt="..." srcset="medium.png 1000w large.png 2000w" />

This uses the small version by default, but on larger screens the browser will download and use either the medium or large version of the image. All we have to do is make the three versions and bung them in our /images folder.

The general rule here is to use an image of the same dimensions as the original and just scale it down to make the smaller versions. As Chris Coiyer says:

Most responsive images uses will be: “I have multiple versions of this graphic. Here they are, use the right one.”

The picture element

The picture element is far more powerful, but also more complex. It allows us to do a bit more at direction as our image size changes – we can use images of different dimensions and control how they are displayed using media query-like rules. A quick google will turn up umpteen articles on how to do this.

Images on this website

Right now, most images on this site are included via standard markdown image tags, and the generated HTML is pretty simple:

<img src="/uploads/an-image.png" alt="An image" />

By default, these images would display at their natural size, so we’re using some CSS to constrain them to 100% of their container.

img {
  display: block;
  max-width: 100%;
}

Inside essays, this means that smallish images display at their natural size and will not be stretched (we’re using max-width not width), but very large images will be scaled down to fit in the essay container.

The problem with this is that I often include quite large high-res images and set them to full-bleed (more on that later). This is fine for large viewports, but smaller devices will be forced to download the massive high-res file.

The obvious solution is to generate smaller versions of these high-res images and then use srcset to let the browser decide which one to show. Except that this is a blog. And if I have to create multiple versions and write a long chunk of HTML every time I want to include an image in my markdown I’ll just stop writing altogether. Clearly, we need a way to automate this.

While we’re at it, there are a few other things we should consider. Firstly, it’s a good idea to explicitly declare the dimensions of an image in the HTML using the height and width attributes. Assuming we don’t override it with CSS, this prevents reflow by telling the browser how much room the image will take up so it can draw the right sized box before the image has downloaded. So while we’re automating image things we should probably add hight and width to image elements.

What’s more, modern browsers will soon be able to infer the aspect ratio of an image based on these attributes, and use that to draw a correctly-sized content box even if we’ve changed the width with CSS. Cool.

Secondly, HTML now supports native lazy loading via the loading attribute. This is obviously good for performance and is as easy as adding loading="lazy" to our image tags. Addy Osmani has a much more detailed explanation.

This ten-minute video from Jen Simmons foes a great job of explaining how all of this works.

How do we automate this stuff?

Good question. Back when I started this redesign, I made the decision to keep the tech super simple. Here are the principles I defined:

As few dependencies as possible (both build-time and run-time dependancies).
Use defaults wherever possible.
Write as little code as possible.
Do not over-abstract. Avoid fallbacks, polyfills and hacks.
Bake accessibility in.

I really don’t want to add unnecessary complexity to this site. But it feels like this is important enough to add a just little more complexity. If there’s a jekyll plugin that can read my markdown image tags, generate smaller versions of my images and insert appropriate srcset attributes, I’ll take it. Bonus points if it can add width, height and loading attributes too.

My initial search actually led me to some awesome plugins for Eleventy. This one does some cool lazy-loading with javascript and data URLs, this one creates picture elements, this one does just what I want for cloud-hosted images and this one basically does what I want but without the bonus points.

Reading though the source code of these was super interesting, and had nudged me to look further at Eleventy (there are some strong arguments for moving this site to it). But since we’re on Jekyll here, none of these are much use. What we need is the Jekyll Responsive Image plugin.

This looks like it solves half the problem. It lets us specify our own template for the generated image HTML which means we can add width, height and lazy loading ourselves. The only downside is that we have to use a liquid tag rather than standard markdown to insert images. No thanks.

And then jekyll hooks came to the rescue with this tutorial from Ivo Valchev. Let’s walk through the process…

Install the stuff

The plugin uses Rmagick which is a wrapper around imagemagick which is – and has always been – a nightmare. So first step is to update or install it and then try installing the gem manually.

brew install imagemagick
gem install jekyll-responsive-image

Now we can add it to our Gemfile and Jekyll config as per the README. There are a lot of config options available but I started with these: a path to the template, the sizes to generate and an instruction to only save the generated files in the build folder.

responsive_image:
  template: _includes/responsive-image.html
  sizes:
    - width: 480
    - width: 800
    - width: 1400
  save_to_source: false

How we need to create our template. I stole most of this straignt from the docs, but I’ve added lazy loading and width/height attributes.

{% raw %} {% capture srcset %} {% for i in resized %} /{{ i.path }} {{ i.width }}w, {% endfor %} {%
endcapture %}
<img
  src="/{{ path }}"
  alt="{{ alt }}"
  loading="lazy"
  srcset="{{ srcset | strip_newlines }}"
  width="{{ original.width }}"
  height="{{ original.height }}"
/>
{% endraw %}

So far so good. We can now insert responsive images with

{% raw %} {% responsive_image path: image.jpg alt: "My Image" %} {% endraw %}

To get this working with standard markdown, we need to register a hook that replaces markdown image syntax with this new tag at build-time. We can create _plugins/img_tag_transform.rb and add the following.

Jekyll::Hooks.register :posts, :pre_render do |post, _payload|
  docExt = post.extname.tr('.', '')
  post.content = post.content.gsub(/!\[(.*)\]\(([^\)]+)\)(?:{:([^}]+)})*/, '{% raw %}{% responsive_image path: \2 \3 %}{% endraw %}')
  post.content = post.content.gsub 'path: /', 'path: '
end

It’s a bit hacky, but it works.

Is it worth it?

My biggest concern with this approach is the added complexity. Not only have I added Imagemagick as a dependancy, I’ve also added a new jekyll plugin and a slightly hacky custom plugin.

For now, this feels like an acceptable trade-off, but if I find myself adding more similar stuff in the future I’ll have to revisit this and reconsider the value/complexity ratio.

Full-bleed Images

While we’re on the subject of images, I’ve also added a few utility classes to make my images a little more interesting. Normal images are constrained to the width of the element they appear in, but sometimes I want full-bleed images that extend out to the edges of the viewport, like this:

We can do this with a utility class and some calc() magic.

.essay {
  .full-bleed {
    width: 100vw;
    margin-left: calc(50% - 50vw);

    // For images that are not wide enough to fill the gap
    display: flex;
    justify-content: center;
    align-items: flex-start;
  }
}

These styles are applied to the container rather than the image itself so that images smaller than the container are never scaled up. We can apply this style in markdown like this

{% raw %}
{:.full-bleed}
![Image](/uploads/2020-07-02-hot-air-baloon.jpg)
{% endraw %}

Which will produce the following HTML

<p class="full-bleed">
  <img src="/uploads/images.jpg" alt="Image" ... />
</p>

As well as full bleed, I’ve also added classes for left and right bleed

.essay {
  .left-bleed {
    margin-left: calc(50% - 50vw);
    display: flex;
    justify-content: flex-end;
    align-items: flex-start;
  }

  .right-bleed {
    margin-right: calc(50% - 50vw);
    display: flex;
    justify-content: flex-start;
    align-items: flex-start;
  }
}

Summing up

Although it’s ben years since I’ve built a proper website like this, I’ve kept myself fairly up-to-speed with developments in CSS. Digging into responsive images has been a nice reminder that there is a whole raft of standards that I’ve ignored and know very little about. I’m now itching to explore some of the other stuff that I remember being discussed and has since matured. I expect I’ll have a play with with SVG (a lot has changed), web components and browser APIs for audio, motion and the like sometime.

That said, it wasn’t really my intention to go this deep into any performance-related stuff at this stage of the redesign, so while I’m tempted to follow up on this with a load more optimisation I’m gong to force myself back into design mode for a little while and focus on getting the non-blog bits of the site looking nice. Until next time.

There was an excellent article on this at the time, but I can’t seem to find it. ↩

Website Redesign Part XI - Code Blocks and Section Rules

Sun, 28 Jun 2020 00:00:00 GMT

I spent a long time [deciding on a typeface]({% post_url 2020-06-20-website-redesign-v %}) for these essays and I don’t want to spend nearly as long on code snippets. Although this series involves a lot of code snippets, I generally write about code a lot less than I used to, so it doesn’t make sense to spend ages on this. I use the wonderful Operator Mono in my text editor and I briefly considered paying for a web license so I could use it here too. But while I love it, it’s quite unusual and is definitely not suited to everyone’s taste. Both the typeface itself and the act of buying a web license are the opposite of simple, one of my stated values for this site. So instead, I’ll stick with the same requirements I used before: open source, ideally with variable and static versions, with nice ligatures and a range of weights.

The first thing that came to mind was Fira Code, an extension of Mozilla’s Fira Mono which was designed specifically for legibility. Fira Code adds a bunch of ligatures for character combinations commonly used in programming, as well as making a few adjustments to make code more readable.

The CSS

Although Fira Code is available via google Fonts it doesn’t support all the opentype features I want, so I ended up cloning the repo and moving TFF, WOFF and WOFF2 versions into the the assets folder like I did for Literata. They’re included in webfonts.scss and have a custom property set just like the other fonts too.

:root {
  --font-code: 'Fira Code', 'Inconsolata', monospace;
  @supports (font-variation-settings: normal) {
    --font-code: 'Fira Code Variable', 'Inconsolata', monospace;
  }
}

Since we want to use Fira code everywhere there’s code, we can set this as the default font for all code elements, whether inside essays or not. We can also use some of the advanced stylistic settings to turn on a sans-serif lowercase ‘r’ and put gaps in double equals signs. I think this makes code a little more readable.

code {
  font-family: var(--font-code);
  font-feature-settings: 'ss01', 'ss08';
  // sso1 = sans-serif lowercase "r"
  // ss08 = Gaps in double/tripple equals
  // See https://github.com/tonsky/FiraCode/wiki/How-to-enable-stylistic-sets
}

Fira code has a bunch of other features like this

Styling inline code

We’ll set the font size to the same as the samm-caps we’re using for abbreviations, which is about equal to the x-height of the body copy. Adding a border, background and a little padding to the left and right is the simplest thing I can think of to differentiate inline code snippets. We’ve also prevented breaking spaces with white-space: pre, though I might need to revisit this if I end up writing some very long inline code snippets.

.essay code {
  font-size: 0.85em;
  padding: 0 0.5ch;
  background-color: rgba(0, 0, 0, 0.05);
  border: 1px solid rgba(0, 0, 0, 0.1);
  border-radius: 1px;
  white-space: pre;
}

Styling code blocks

We already set up some basic styles for <pre> elements, so all we need to do is remove the styles we just set for any <code> elements that appear within them.

pre {
  border: 1px solid rgba(0, 0, 0, 0.2);
  padding: calc((1em * var(--base-lh)) - 2px);
  background: rgba(0, 0, 0, 0.05);
  overflow-x: scroll;

  code {
    padding: 0;
    background-color: transparent;
    border: none;
  }
}

The final thing to do is add syntax highlighting. Since we’re using Jekyll, any fenced code blocks that have a language defined on them will use Rouge to apply syntax-highlighing classes in the same way Pygments does. This means we can take an existing theme stylesheet and include it in our bundle. I used this one and tweaked a few of the colours slightly. I’ll come back to this once I have a colour palette for the site.

Horizontal Rules

I’ve always liked the section mark (§) and thought it might be nice to superimpose this on horizontal rules. The code for this is pretty simple – we’ll add a psuedo-element containing the mark and use flexbox to position the hr and psuedo element on top of each other. A bit of padding and a background on the psuedo element creates a gap in the line, and a little nudging with translateY vertically centres the mark.

.essay hr {
  display: flex;
  align-items: center;
  justify-content: center;

  border: 0;
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  &:before {
    content: '§';
    transform: translateY(-0.15em);
    background: var(--color-white);
    padding: 0 0.5em;
  }
}

It would also be nice to add a little more margin than usual either side of the rule. Since we’re using only top-margin to maintain vertical rhythm, we need to use the sibling selector to add margin to the element immediatly following the <hr> as well as the rule itself.

.essay hr,
.essay hr + * {
  margin-top: calc(2em * var(--base-lh));
}

Website Redesign Part IX - Lists

Thu, 25 Jun 2020 00:00:00 GMT

Lists are incredibly useful for certain sorts of article. I tend to make quite heavy use of lists in some of my articles, so it’s important that I give some thought to how they’re styled. Since I’m going for a “bookish” vibe, I’d rather keep the vertical rhythm the same as for all the other text on the page, so I’ll be sticking with the standard top-margin of 1 × line height and leaving the margin and line height of the list items as they are. With that decision made, we only need to worry about styling the list markers: bullets, numbers and checkboxes.

After a bit of playing around, I think it’s a bit too jarring to hand the markers in the margin and flush-align the text. If this was for print it might look less wierd, but we’re so used to seing indented lists on the web that it just feels wrong for this medium. So we’ll aim to flish-align the markers and set 1em of left-padding on all list items. As long as we keep the markers set to outside we’ll end up with the start of out text neatly aligned at 1em from the left margin.

.essay li,
.essay li {
  padding-left: 1em;
}

Bulleted Lists

After a bit of playing around, I’ve decided to keep the bullets super sumple. We’ll just use a mid-sized bullet and ad a little left padding to pull them inline with the margin.

.essay ul {
  padding-left: 0.4em;
  list-style-type: '•';
}

Annoyingly, iOS Safari and Chrome don’t yet support string values for list-style-type, but since they both support @supports, we can add a fallback.

@supports (not (list-style-type: '•')) {
  &:not(.task-list) {
    // Begin fix for browsers that don't support list-style-type: <string>
    list-style-type: none;
    padding-left: 0.9em;
    li {
      padding-left: 0.5em;
      position: relative;
      &:before {
        content: '•';
        position: absolute;
        left: -1em;
      }
    }
    // End fix
  }
}

Numbered Lists

We’re decreasing both the size and optical size for numbers to the same as we did for for abbr elements, and falling back to the Literata Caption if variable fonts aren’t supported. We’re also making them slightly bolder than abbreviation since, as markers, it’s important they stand out a little more. We’re then adding some left padding to bring the first character inline with the left margin: single digit numbers will be flush with the margin while extra digits will extend outwards to the left.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam tincidunt mauris eu risus.
Vestibulum auctor dapibus neque.
Nunc dignissim risus id metus.
Cras ornare tristique elit.
Vivamus vestibulum ntulla nec ante.
Praesent placerat risus quis eros.
Fusce pellentesque suscipit nibh.
Integer vitae libero ac risus egestas placerat.
Vestibulum commodo felis quis tortor.
Ut aliquam sollicitudin leo.
Cras iaculis ultricies nulla.
Donec quis dui at dolor tempor interdum.

.essay ol {
  padding-left: 0.8em;

  ::marker {
    font-size: 0.85em;
    font-family: 'Literata Caption', Georgia, 'Times New Roman', serif;
    font-weight: 600;

    @supports (font-variation-settings: normal) {
      font-family: 'Literata Variable', Georgia, 'Times New Roman', serif;
      font-variation-settings: 'opsz' 10;
      font-weight: 610;
    }
  }
}

Checklists

Jekyll allows us to use Github Flavoured Markdown task lists, and I occasionally make use of this in my articles. They work like this

- [ ] Item 1
- [x] Item 2
- [ ] Item 3

This will produce the following output and HTML

Item 1
Item 2
Item 3

<ul class="task-list">
  <li class="task-list-item">
    <input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Item 1
  </li>
  <li class="task-list-item">
    <input
      type="checkbox"
      class="task-list-item-checkbox"
      disabled="disabled"
      checked="checked"
    />Callout inline styles
  </li>
  <li class="task-list-item">
    <input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Item 2
  </li>
  <li class="task-list-item">
    <input type="checkbox" class="task-list-item-checkbox" disabled="disabled" />Item 3
  </li>
</ul>

We can use these generated classes to style the checkboxes. We’ll remove the default list styles and padding and set up each li as a flex container. Each have two flex items – the checkbox and the text. This ensures that the text doesn’t wrap dowin under the checkbox for multi-line items.

.task-list {
  list-style-type: none;
  padding-left: 0;
}

.task-list-item {
  position: relative;
  display: flex;
  align-content: center;
  padding-left: 0;
}

Next, we’ll remove the default appearance, set a hight and width and nudge the box with some margin so it’s about the same height as lowercase characters and is aligned a tiny bit above the baseline. We’ll also add a border of our own.

.task-list-item-checkbox {
  margin: 0.5em 1em 0 0;
  height: 0.7em;
  width: 0.7em;
  min-width: 0.7em; /* Prevent flex-shrinking */

  -webkit-appearance: none;
  -moz-appearance: none;
  -o-appearance: none;
  appearance: none;
  outline: none;

  border: 1px solid rgba(0, 0, 0, 0.3);
}

Finally, we’ll add a tick (✓) to any that are checked, style it and position it properly within the box.

.task-list-item-checkbox:checked:before {
  content: '\2713';
  position: absolute;
  top: 0.645em;
  font-size: 0.6em;
  font-weight: 600;
}

To make this work properly on iOS, we also need to explicitly set the background and border-radius, and bump the opacity of disabled checkboxes up to 1.

.task-list-item-checkbox {
  // ...
  border-radius: 0px;
  background: transparent;
  //...
}

.task-list-item-checkbox[disabled] {
  opacity: 1;
}

And that just about wraps up styling for lists. I’m sure I’ll revisit some of this when I start to add colour to the site, but for now this is a definite improvement over the defaults.

Website Redesign Part X - Links

Thu, 25 Jun 2020 00:00:00 GMT

Hyperlinks are what makes the web special. They allow us move seamlessley from idea to idea at our own pace. While we tend to read books sequentially, websites are more like choose your own adventure books – hyperlinks let us choose how we experience them. And it’s that way by by default. So links should be pretty prominent on this site. But at the same time, an article peppered with bright blue links is not easy on the eye. Where links are incidental to the text (as many are), they interrupt the flow of reading. I’ve spent a fair bit of time thinking about how I want links to work and I basically have two requirements.

They must get out of the way when reading and not be a distraction.
They should obviously be links for users who are looking for them. This includes differentiating between unvisited and visited links.

Let’s start off by removing styles from hyperlinks that have a class. This gives us a good starting point for styling UI links and also deals niceley with the footnote links that jekyll creates.

a[class] {
  text-decoration: inherit;
  color: inherit;
}

The default clours in most browsers are blue for unvisited links and purple for visited links, so I like the idea of sticking with that since it’s alrreasy well-understood by most users. Rather than colouring the whole word, we might be able to get away with colouring just the underline. This makes the links far less intrusive. we can also pick much less saturated colours than the default.

The hover styles can afford to be a lot bolder and brighter. Something like…

We can achieve this by setting links to inherit their text colour from their parent and styling the underline with text-decoration-color. We’ll also add a subtle transition on hover and force the underline width to 1px on browser that support it.

--color-link-underline: rgba(111, 131, 222, 0.5);
--color-visited-link-underline: rgba(188, 127, 219, 0.5);
--color-active-link-underline: rgb(255, 30, 28);

a:not([class]) {
  color: inherit;
  text-decoration-color: var(--color-link-underline);
  text-decoration-thickness: 1px;
  transition: all 0.25s;

  &:visited {
    text-decoration-color: var(--color-visited-link-underline);
  }

  &:hover,
  &:active {
    text-decoration-color: var(--color-active-link-underline);
    color: var(--color-active-link-text);
  }
}

This feels okay on devices with a pointer. Although the underlines are subtle, if the user isn’t sure it’s a link, they can mouse over and the transation will make it pretty clear. But on touch devices this is impossible, so it feels sensible to make the links a little more ovbious somehow. On mobile devces the text also has a much smaller measure and therefore more multi-line links, whihc looks kinda ugly.

We can alter our code to cremove the underline on touch devices and instead change the text-colour. I’m using a similar blue and purple here, but it’s nececarrily much darker and without an alpha channel. I tried to use a colour that didn’t affect the typographic colour of the text. If you try squinting and looking at the mobile version the links shouldn’t feel lighter or heavier than the rest of the text.

a:not([class]) {
  //...

  @media (pointer: coarse) {
    text-decoration: none;
    color: var(--color-link-text);
  }

  &:visited {
    text-decoration-color: var(--color-visited-link-underline);

    @media (pointer: coarse) {
      color: var(--color-visited-link-text);
    }
  }

  //...
}

Finally, I want to do something about the outline browsers apply when a link is focussed by keyboard. I don’t want to do too much with this for accessibility reasosns, so we’ll just change it from blue to our brand red using the focus visible psutedo-selector. I’ll revisit keyboard navigation once I have a color palette for the site.

a:focus-visible {
  outline: 3px solid var(--color-red-trans50);
}

Website Redesign Part VII - Responsive Typography

Mon, 22 Jun 2020 00:00:00 GMT

Having settled on a typeface for my essays, it’s time to set up some basic typography. In the past, I’ve spent a lot of time building maths-based ype systems with myriad variables and functions and it’s so tempting to go down that route this time and try to create a system that caters to every eventuality. But that would be at odds with my simplicity value, so for the time being I’ll stick to the basics. We’re going to set up a base font size and line height and scale that as the viewport grows. We’ll also add just enough whitespace to create a nice vertical rhythm and create some visual hierachy by styling the headings. Everything else can wait.

Base font-size

We’ll start off by setting the font-size of the HTML element to 100%. This makes sure that 1rem will always represent the default font-size of the device or browser - usually 16px. We’ll use rems and ems to define pretty much every other size in the site, so we’ll also set the body font-size in rems so it’s inherited by other elements.

We also want to reset the heading sizes to 1em. We’ll probably redefine some of these later but I always think it’s a good idea to start with one size for all elements, since it often makes sense to differentiate headings with weight, style or color rather than size. We’re using ems rather than rems here because we want them to scale if we change the font-size on their container.

html {
  font-size: 100%;
}

body {
  font-size: 1rem;
}

h1,
h2,
h3,
h4,
h5 {
  font-size: 1em;
}

Scaling Type Size

We can use the new CSS clamp() function to enable responsive type without the need for a million media queries. This will scale the type from 1rem (16px) to 1.375rems (22px). The middle value is calculated using both viewport units and rems: the vw causes the type to scale with the viewport width and the rems ensure that user-initiated text resizing still works. I arrived at 0.6rem after a bit of experimentation.

.essay {
  font-size: clamp(1rem, calc(0.6rem + 1vw), 1.375rem);
  transition: font-size 0.1s;
}

Hyphens

Enabling hyphenation can make a big difference to readability on small screens, where an uneven right rag can cause very short lines. We can set up a SCSS variable for breakpoints and then use a media query to turn hyphenation off for larger viewports.

$breakpoint-m: 42em;

.essay > p {
  -webkit-hyphens: auto;
  hyphens: auto;

  @media (min-width: $breakpoint-m) {
    -webkit-hyphens: none;
    hyphens: none;
  }
}

Vertical rhythm

The main purpose of a baseline grid is, unsusprisingly, aligning the baselines of text. This makes a huge difference when we have multiple columns of text with differing fonts, sizes and the like.

While this makes a huge difference to the feel of a page, the fluid nature of web pages (and the way line-height works) makes this quite hard to do consistently. We can avoid this problem entirely by only having one column.

But baseline grids can also provide a sense of vertical rhythm – something we can do on the web without too much effort. We just need to work out how high each of our lines is and use multiples of that measurement to space things out vertically. (It can also make a good measurement for horizontal spacing.)

For the time being, we’ll keep our vertical rhythm super simple. First, we’ll remove all top and bottom margins - I’ve chosen to do this in my base stylesheet rather than just for the essays. Then we’ll set up a custom property to hold our base line-height and use that to set the line-height for all the elements in the essay container.

*,
*::before,
*::after {
  margin-top: 0;
  margin-bottom: 0;
}

:root {
  --base-lh: 1.5;
}

.essay > * {
  line-height: var(--base-lh);
}

We can now use this base line-height to set margins on our headings, paragraphs and the like. We can use the lobotomized owl selector to target all elements that have something above them and add a margin equal to our line-height. For now, we’re using ems so the margins will scale with the font-size.

> * + * {
  margin-top: calc(1em * var(--base-lh));
}

We can add top-margin in the same way to other elements. By sticking with top-margin and never using margin-bottom, we have a simpler mental model for how spaces between elements are calculated: we never have to worry about margin collapsing or make a decision on whether to use top or bottom margin.

While we’re here, I also used this tto set some horizintal padding on blockquotes

blockquote {
  border-left: 2px solid rgba(0, 0, 0, 0.2);
  padding-left: calc((1em * var(--base-lh)) - 2px);
  font-style: italic;
  margin-left: 0;
}

Styling Headings

Looking through my articles I dont’t tend to use H1s very often at all, apart from as the article title. This makes sense from a semantic point of view so we can assume that all H1s inside .essay are an article title. I tend to use H2 and H3 fairly often to break my articles into sections, and H4s often appear in logner articles. I rarely, if ever use H5-6.

With this in mind, it makes sense to keep things super-simple. Here’s what I initially settled on…

Aside from H1s, all are set at the same size as the body copy. Five and Six are styled identically in italic with the same weight and margins as paragraphs. Four is set in small-caps with a semibold weight, again with the same margin as paragraphs. Three and Two are both set in bold with a bigger top margin, two being differentiated by being uppercase.

The article title is bigger, and increases is size on larger viewports.

.essay > h1 {
  font-size: 2rem;
  @media (min-width: $breakpoint-m) {
    font-size: 3rem;
  }
  font-weight: 500;
  font-variation-settings: 'opsz' 50;
  line-height: 1.3;
}

.essay > h2 {
  font-weight: bold;
  text-transform: uppercase;
  letter-spacing: 0.15ch;
  margin-top: calc(2em * var(--base-lh));
}

.essay > h3 {
  font-weight: bold;
  margin-top: calc(2em * var(--base-lh));
}

.essay > h4 {
  font-weight: 600;
  text-transform: lowercase;
  font-variant: small-caps;
  letter-spacing: 0.05ch;
}

.essay > h5,
.essay > h6 {
  font-weight: normal;
  font-style: italic;
}

I’ve also turned off styling for any links inside headings by having them inherit their styles from the heading elements.

h1,
h2,
h3,
h4,
h5 {
  a,
  a:visited,
  a:hover,
  a:active {
    color: inherit;
    text-decoration: inherit;
  }
}

I’m generally pretty happy with this, except for one thing. I use level two headings more than any other and because I’ve set them in uppercase I’m missing out on the loveley discretionary ligatures that Literata includes. So I might want to revisit this soon.

Website Redesign Part VIII - Adding some style

Mon, 22 Jun 2020 00:00:00 GMT

The last part focussed on setting up a basic typographic system using margins and heading styles. In this part, I’m going to make a bunch of little tweaks to the typography of these essays. Over the next few months I’ll probably make a whole host of little incremental changes like this.

Old-style Figures & Fractions

Most good typefaces contain two sorts of figures. Lining figures are designed to sit on the baseline and are generally all the same height. They’re great for headings, tables and UI. Old-style figures overhang the baseline and often vary in height. These are great for setting numbers in body copy.

I’m using the default lining figures in most places, but I want to use old-style figures in paragraphs, lists and blockquotes (eg. 1957). I also want to use proper fractions like this → 3/4.

.essay > p,
.essay > ol,
.essay > ul,
.essay > blockquote {
  font-variant-numeric: oldstyle-nums diagonal-fractions;
}

Bold

Where variable fonts are supported, I’m making strong tags a little bolder than normal.

strong {
  font-weight: 600;
  @supports (font-variation-settings: normal) {
    font-weight: 625;
  }
}

Abbreviaions

Abbreviations like HTML nearly always look best rendered in small caps with a little space between the letters, so I’m doing that for any <abbr> elements:

Use small caps and transform the text to lowercase to we don’t get any proper caps mixed in.
Space out the letters a bit (I’m using ch here, which is based on the width of the “0” character).
Use a low optical size and fall back to Literata Caption where variable fonts aren’t supported.
Use a slightly heavier weight than normal - roughly equivilent to Semibold.
Set the cursor to help is it has a title attribute.
Make the dotted underline almost invisible, and position it under the baseline rather than on the baseline.

.essay abbr {
  text-transform: lowercase;
  font-variant: small-caps;
  letter-spacing: 0.05ch;

  font-family: 'Literata Caption', Georgia, 'Times New Roman', serif;
  font-weight: 400;
  font-size: 0.85em;
  @supports (font-variation-settings: normal) {
    font-family: 'Literata Variable', Georgia, 'Times New Roman', serif;
    font-variation-settings: 'opsz' 10;
    font-weight: 410;
  }

  text-decoration-color: rgba(0, 0, 0, 0.15);
  text-underline-position: under;

  &[title] {
    cursor: help;
  }
}

First line & Drop Caps

I’m experimenting with adding drop-cap and small caps for the first line. I’m not yet sure whether I really like this, so will probably revisit later on. I’ve also added hanging punctuation for paragraphs (only supported by Safari at the moment)

.essay > p {
  &:first-of-type::first-line {
    text-transform: lowercase;
    font-variant-caps: small-caps;
    font-weight: 500;
    @supports (font-variation-settings: normal) {
      font-weight: 525;
    }
  }

  &:first-of-type::first-letter {
    text-transform: uppercase;
    float: left;
    font-size: 4em;
    line-height: 1;
    padding-right: 0.5ch;
  }
}

That’s it for now. I’ll cover lists, code blocks and links in future articles.

Website Redesign Part VI - Adding a Typeface for Essays

Sun, 21 Jun 2020 00:00:00 GMT

After much messing about with typefaces, I think I’ve narrowed the choice for essay copy down to two contenders: Literata and Lora. Both feel “bookish” and are designed for long-form reading on screens. Both are open source and available as variable fonts as well as static. Version 3 of Literata not only allows us to vary the weight, but also the optical size. The static version has four optical sizes – each in various weights and italic versions.

The caption variant is designed for small sizes (around 7pt), the regular variant for body copy and the deck and display variants are meant for headings. The variable version gives me pretty fine-grained control over this.

Since I’m not sure which of these two typefaces I prefer, I’ve decided to bring both of them into the website and switch them out regularly as I’m working to see if one starts to grow on me.

Although I initially wanted to serve fonts via Google Fonts, I’ve changed my mind. One of my technical principles is as few dependancies as possible, and these are both open source I can host the myself. I was finally tipped into this decision because Google Fonts doesn’t have the latest version of literate available.

Building the fonts

I’ve never had to build fonts from source before, but after much yak shaving to update my python install and various home-brew packages I was able to run the three build scripts from the Literata repo. It toook a while to work out what they do, but essentially:

build-static.sh builds a bunch of TTF font files from source using the fontmake utility. This produces a lot of files – one for each weight/style/optical-size combination.
build-var.sh does the same, but for the variable fonts. It only produces two TTFs: roman and italic.
build-woff.sh takes the TTFs we just built and makes woff and woff2 versions using the sfnt2woff and woff2_compress utilities.

Since the Lora repo already includes TFF files, I just tweaked build-woff.sh a bit and used it to make corresponding woff/woff2 files with the same folder structure as Literata.

After renaming the wolf and woff2 versions of the variable fonts to remove the brackets, I ended up with this in the fonts directory of this site…

The whole thing comes in at a whopping 28MB, but that’s okay because I’m not actually gonna use most of these in production. I just want them to play with for the moment.

@font-face Declarations

I borrowed the Literata font-face declarations from Jason Pamental’s amazing Moby Dick project and added some similar ones for Lora. I’m pretty sure I’m gonna borrow a lot more from that project over the next few months. They generally follow this format:

@font-face {
  font-family: 'Literata Caption';
  font-style: italic;
  font-weight: 600;
  src:
    url('../fonts/literata/woff2/Literata-7ptSemiBoldItalic.woff2') format('woff2'),
    url('../fonts/literata/woff/Literata-7ptSemiBoldItalic.woff') format('woff');
  font-display: swap;
}

It’s been a long time since I actually looked at a @font-face declaration, so if you need a reminder too:

We’re writing a declaration for Literata-7ptSemiBoldItalic. This is the caption-sized version, in Semibold italic.
The first three lines specify when this font file should be used. In this case when we set font-family: 'Literata Caption' with a weight of 600 and an italic font-style.
The src attribute specifies the path to the woff2 version first and falls back to the woff version if that’s not supported (woff 2 offers much better compression than woff 1). Since woff is widely supported we’re not including any other fallbacks.
font-display tells the browser how to handle font loading. In this case, the browser will render the text in a fallback and then our font in once it’s loaded.

The variable font declarations look much the same, but include two values for font-weight: the minimum and maximum at which it should be used.

Using the fonts

Our current CSS sets the font-family for essays using a custom property.

.essay {
  font-family: var(--font-essay);
}

As the design evolves, we’ll definitely end up with a more complex system for this but for now we can just update the variable to use Literata. We can also tell browsers that support variable fonts to load that instead of the static version.

:root {
  --font-essay: 'Literata', Georgia, 'Times New Roman', serif;

  @supports (font-variation-settings: normal) {
    --font-essay: 'Literata Variable', Georgia, 'Times New Roman', serif;
  }
}

I’d like to provide a more robust fallback stack (see this issue) but for now, we’ll just go to Georgia and TNR.

Some basic Open Type Features

Literata includes some lovely discretionary ligatures, but we don’t want them in the body copy. I’ve already set font-variant-ligatures: common-ligatures; on the body in my base stylesheet, but we’ll turn on discretionary ligatures for headings across the whole site:

h1,
h2,
h3,
h4,
h5 {
  font-variant-ligatures: common-ligatures discretionary-ligatures;
}

So where are we at?

I’ll see which of these two feels best as I work on the site over the next few weeks.

Reflection on Learning

One of my goals for this project was my own learning, and after some reflection on that I’ve learned a fair bit during this wanter into web typography…

I finally read The Elements of Typographic Style cover-to-cover.
I’ve learned a lot about type just by really looking at a bunch of different faces.
I’ve learned a bit about how digital fonts are made and the tools used to build them.
I’ve started to get excited about opentype features in CSS.

I’ve also re-learned that it’s easy to get blocked by indecision on a personal project like this. I could have wasted months trying to find the perfect article typeface and still not been happy with it. As with most things, any decision is better than no decision. Especially when it’s reversible.

Website Redesign Part V - Choosing a Typeface for Essays

Sat, 20 Jun 2020 00:00:00 GMT

I love typography, but I’m not that good at it. One day I’ll take a typography course at a a design school, but in the meantime I need to choose some typefaces for this website. I’m fairly confident I’ll need two rather different typefaces in the end. A essay face for setting longer-form writing and a UI face for everything else. I like the idea of using a very modernist face for the UI and something more old-fasioned and bookish for the essays. It might be hard to make this work but it seems to chime will with my personality – I’ve always had a tendancy to mix super-modern with traditional oldy-worldy. Trainers and Tweeds, if you will.

I’ll explore this in more detail in a future article, but for the time-being let’s revisit the four core values I decided on in Part I: Simple, Beautiful, Authentic and Content-first. Choosing and pairing typefaces is hard, so to keep things simple we’ll start by looking for one. And that last value makes a strong case for starting with the content.

What do I need from an Essay Typeface

The most obious requirement is that it’s very readable. And in particular, on screens. It needs to get out of the way and put the content first. It also needs to work well in dark mode, which probably rules out faces with very high stroke contrast (and therefore thin stokes). And to keep things simple, it should also work for headings, quotes, captions and the like –I’d rather not use a third face for this.

As far as feel goes, I’m going for bookish but definitely of the digital world. This probably means a serif, but maybe not a really traditional one.

So I’m going to start by looking for faces that are digital natives (ie not redrawings of print faces), which have been designed specifically for readability on the screen. There are a few technical constraints to think about first, though.

Technical Constrains & Features

It must be open source. While I have a subscription to Adobe Fonts I don’t want this project to depend on a paid service. If I can find something that’s hosted on Google Fonts so much the better. Because simplicity.

I’d prefer a variable font. Mostly because they’re new and shiny and fun to play with, but also because it’s likely to reduce total page weight. If I go with a variable font, it also needs to have a static version – not all browsers properly support variable fonts yet.

I’ll need a good selection of weights in both roman and italic. Probably 200 (light), 400 (normal), 700 (bold) as a minimum. I’ll also want support for the following opentype features¹:

Proper small caps
Both Old-style and and Lining figures
Nice default and discretionary ligatures
Fractions

It would be nice to have a proper superscript for footnotes, but this is hardly crucial.

Checklists

I’ve bubbled all of that down into a couple of checklists to help me evaluate fonts. On reflection, none of the items are really mandatory – it’s important I keep an open mind while I’m exploring. But they’re good starter to help narrow down the field.

Technical Features

Open source?
Available on Google Fonts?
Variable Font? (with static version as fallback?)
Wights at least: light (200), normal (400) and bold (700) in italic and bold.
Proper Small Caps
Old-style and lining figures
Nice ligatures (including discretionary)
Proper Fractions
Other OpenType features that might be fun/useful?

Style

The Shortlist

After a lot of exploration, I’ve settled on five candidates. None hit all the criteria in the checklists, but a few get pretty close. And I like them all.

Spectral

(Google font page)

Specral was designed in 2017 as a screen-first typeface. This article goes into a lot more detail.

Spectral is a new and versatile serif face available in seven weights of roman and italic, with small caps. Intended primarily for text-rich, screen-first environments and long-form reading

Over the past decade, the amount of attention given to readability studies by typeface designers has yielded either bland and conservative results, or overwrought “solutions.” This is more pronounced in screen typefaces than those made for print media, where common pitfalls include overly simplified shapes, “friendly” letters, and facile tricks like unnecessarily upright italics.

In response, Spectral takes an unambiguous stance: Screen typefaces should not look like caricatures of themselves. They should instead be functional text designs that stay interesting enough to convey the many voices that contemporary users need.

At first glance, this seems like it might be a great choice, but after some experimentation the very high stroke contrast makes it feel a bit too bookish. It’s a bit too spindly, somehow. It also doesn’t work that well on dark backgrounds at small sizes.

If I was setting a book on the web, I’d definitely consider this though.

Lora

(Google font page)

Lora is a well-balanced contemporary serif with roots in calligraphy. It is a text typeface with moderate contrast well suited for body text.

A paragraph set in Lora will make a memorable appearance because of its brushed curves in contrast with driving serifs. The overall typographic voice of Lora perfectly conveys the mood of a modern-day story, or an art essay.

Technically Lora is optimised for screen appearance, and works equally well in print.

Lora was designed by Olga Karpushina in 2011. It’s definitely the least unusual of the five, though the fairly upright italic is beuatiful. This is definitely one that would get out of the way and put the content first.

Alegreya

(Google font page)

Alegreya is a typeface originally intended for literature. Among its crowning characteristics, it conveys a dynamic and varied rhythm which facilitates the reading of long texts. Also, it provides freshness to the page while referring to the calligraphic letter, not as a literal interpretation, but rather in a contemporary typographic language.

The italic has just as much care and attention to detail in the design as the roman. The bold weights are strong, and the Black weights are really experimental for the genre. There is also a Small Caps sister family.

Not only does Alegreya provide great performance, but also achieves a strong and harmonious text by means of elements designed in an atmosphere of diversity.

I love the fact that Alegreya has a small caps variant and is part of a super family that includes a sans-serif version - I was wondering if I could use the sans version for UI copy. But much like Spectral, it almost feels too caligraphic and oldy-worldy-bookish.

Literata

(Google font page)

Literata is probably one of my favourites. It feels right for the job, somehow. It’s got a huge array of varients plus a variable version and some lovely ligatures. It was commissioned by Google and designed by TypeTogether in 2015 and is the default font family in Google Play Books. I’m not sure I like the idea of using a face that so many folks will associate with Google, but as far as versitility and reading experience goes, this is definitely on the shortlist.

Bitter

(Google font page)

Motivated by my love for the pixel I designed Bitter. A “contemporary” slab serif typeface for text, it is specially designed for comfortably reading on any computer or device. The robust design started from the austerity of the pixel grid, based on rational rather than emotional principles. It combines the large x-heights and legibility of the humanistic tradition with subtle characteristics in the characters that inject a certain rhythm to flowing texts.

Bitter has little variation in stroke weight and the Regular is thicker than a normal ‘Regular’ style for print design. This generates an intense color in paragraphs, accentuated by the serifs that are as thick as strokes with square terminals.

This also scores well when it comes to readability, but the fact it’s slab serifs and very dark color make it feel a bit too unrefined for use here. It’s still on the shortlist though.

Here’s a good overview of CSS opentype features. ↩

Website Redesign Part III - A Base to Start From

Tue, 07 Apr 2020 00:00:00 GMT

I’m trying to keep the CSS as minimal as possible here, but I do want a decent blank slate to work from. So I’ve normalised browser styles with normalize.css and set up some of my own base styles.

Reset some basic styles to the way I like them.
Set up some variables and use them for base colours and typography.
Remove styles from all lists that have a class - they’re probably part of the UI, not the content.
Remove styles from links that have a class - same reason.
Set default link styles for body copy.
Remove all animations and transitions for people that prefer not to see them.

I’m sure these will change over time, but here they are for now…

A starting point for article typography

Since I’m writing on this site now, there’ll be a lot more written content. My Content-first value means I should probably start with that, while my Simplicity value means I should probably ignore layout and start by making the article copy as beautiful and readable as I can.

So taking a leaf out of Frank Chimero’s book, I’m starting with a very very simple set of styles for my articles.

I’ll focus in on this soon but until I choose a better typeface, --font-copy is set to Georgia. Like Frank, I still like it.

Website Redesign Part IV - Pages and URLs

Tue, 07 Apr 2020 00:00:00 GMT

I bought this domain specifically so I could have cool URLs like danny.is/doingsomething, so definitely want to use certain URLs, regardless of content. These provide a good starting point for deciding what pages I might want.

danny.is

The homepage, obviously. Since the last redesign this has just shown a list of links to other pages and external services, but I’ll probably change that a bit with this redesign.

danny.is/about

A few paragraphs about me. Perhaps some other stuff.

danny.is/now

A very simple description of what I’m doing at the moment. Inspired by this.

danny.is/writing

An index of my writing. This will definitely include my writing on this site, but I might also include stuff I write elsewhere.

danny.is/reading

Stuff I’m reading. Historically, this has been a big list of links pulled from Pocket and Medium. I want to keep that, but might also include books I’m reading, or recommend.

danny.is/cv

A PDF of my CV.

danny.is/using

Forwards to a Notion page detailing the software and hardware I use. I’m sticking with Notion for the moment because I already have much of this written.

danny.is/meeting

Forwards to a notion page where you can book a meeting with me. I’ve been sharing the full notion link for about a year now, and it’s just occurred to me that setting up this forward makes a lot of sense. Again, I’m sticking with notion because I already have it set up.

Other URLs

I’ve also set up forwards for LinkedIn and youtube, since I find it hard to remember their URLs:

danny.is/linkedin → My LinkedIn profile
danny.is/youtube → My Youtube channel

It seems likely that I’ll also want two new pages…

danny.is/lookingforwork

A “Hire me” page which is only live when I’m actively looking for work.

danny.is/coaching

A page detailing my coaching work. I expect this will be the only page where I care about “marketing”.

Pages I need to design

Ignoring the forwards and the now page, that’s eight pages I need to consider when it comes to design.

Homepage
About
Writing (index)
Writing (article)
Reading
Looking for Work
Coaching
404

There’s a part of me that wants to dive into the design of these pages right away, but I’m resisting the urge. Making the writing that’s already here useable is far more important. Keep it simple, Danny.

Website Redesign Part II - Principles, Goals and Stuff to Keep

Tue, 17 Mar 2020 00:00:00 GMT

Until now, every time I’ve redesigned this website it’s been because I didn’t like how it looked. Every few years, I’ve looked at it and felt like it doesn’t adequately represent me.

When I started this redesign process, I fully expected to feel the same way. But having spent a bunch of time staring at it, I think I still like a lot of what I have.

More accurately, I still really like these two pages…

When I designed them back in 2016 I was going for a modern “Swiss” influenced kinda vibe. I think I want to keep that.

But let’s take a step back for a second and think about my goals.

Goals of this site

First and foremost, it’s a personal expression of me. It’s a place for me to have fun: both with my writing and with design & CSS. So it’s okay if it’s a bit goofy or stuff is a bit broken sometimes.

But it also represents me professionally.

Thankfully, in both cases the primary goal remains the same. To help the reader understand me – Danny.

If I put my UX hat on for a minute, there is a Job To Be Done that I should consider. A subset of visitors to this site are trying to find out if I’m the right person to help them with something.

Similarly – with my marketing and I-need-money-to-eat hat on – there is another subset of visitors that need my help; but neither of us know it yet.

The last thing I want is for my personal site to be some sort of super-optimised landing page for Danny The Professional®. Because that’s no fun. And it’s not at all an expression of me. But I do need to consider these special use cases a bit.

Of course, there are also the random folk who come here to read the stuff I write. They probably just wanna read in peace.

So if I think in terms of actors and their goals:

Danny
- Express himself freely and without constraint.
- Have fun. With writing, design and code.
- Connect with people he can help, or who can help him.
Interested reader
- Read Danny’s words in peace.
- (Perhaps) be notified when Danny writes some new words.
Person checking Danny out
- Find out if Danny is the right person to help them.
- Contact Danny.

This feels like a good set of goals to start with. But they come in a strict order of priority: Danny → Interested Reader → Person Checking Danny Out. This is my personal website, after all.

So here’s a rule I’m gonna try to stick to:

Given a choice between what I want to do and what I feel I should do because [reasons], always choose the former.

Goals of this redesign

As I said in Part I, I’m doing this primarily for two reasons:

I want a simpler, more technology-agnostic website.
I want to write here, not on Medium.

Combined with the website goals up there ☝️, I think I’m trying to achieve the following:

Represent myself more authentically.
Simplify my own mental model for who I am and what I do, as expressed through this site.
Make things more obvious and useful to readers.
Put my writing at the front, and make it beautiful.
Provide somewhere for folks to find out about my work, and how I might be able help them.

I suspect (2) and (3) mean better content organisation and hierarchy, along with some self-imposed constraints. (4) probably means better typography and more focus on the tiny details. As for (5) – that’s probably just a page of its own.

The first one is interesting though. I said earlier that I like the current design. For the first time ever it still feels authentic now that Redesign Time has rolled up. And so it does. At least what there is of it.

And perhaps that’s the problem. My current site is too sparse. Too sanitised. Sure, it has some wacky angles and stuff. But it has no substance.

It also feels a bit cold and unloved. Like a well-machined tool that rarely gets used.

I’d much rather it felt like a hand-made tool that’s used and loved every day. It’ll probably have more dents and scratches, but it will feel much more like home.

Representing Danny more authentically

I recently asked some friends to describe me using as many single words/short phrases as they wanted. The list so far has been a great prompt for reflection and has led me to a fair few blind spots, but I’m still waiting for a lot of folks to come back to me.

I’m hoping that this will help identify some words that I feel authentically represent me.

So where are we at?

Besides the fact that I like my current website, we’ve identified three main actors and their goals. We’ve also established five initial goals for this redesign, and expanded on the most important of them.

Back in Part I I listed four values that felt right as guides for this project.

Simple
Beautiful
Authentic
Content-first

They still feel right to me. And they now have bit more flesh on them.

What about my current website?

Before wrapping this up, I want to take a look at my current website with all this thinking in the back of my mind. I particularly want to look at the two pages I like – the homepage and the 404. Here are some unedited thoughts on them:

They are simple. ✅
They put the content first – even though there is hardly any of it. ✅
There should be more content.
I think the 404 page is beautiful. I love how the colour, type and layout interact. ✅
The homepage is less beautiful. Futura looks pretty bad at very large sizes and the whole thing feels slightly unpolished somehow. It lacks attention to the little details. Inauthentic.
Futura is a lazy choice of typeface - I use it everywhere.
The 404 page feels like an authentic representation of me¹. The homepage less so. This might have more to do with the content than the deign. I talk a lot and am generally friendly, and it feels a bit too minimalist and impersonal. It’s somehow not goofy enough, where the 404 page is. At least the palette feels warm ad cosy.
I’m going for a kinda Bauhaus/Swiss vibe but there’s no grid. I’m a massive nerd for orderly systems and grids, so this feels both inauthentic and like a missed opportunity to create some beauty through mathematics.

Until next time.

Yes I know, “Not Found”. 🙃 ↩

Website Redesign Part I - The Tech

Sat, 14 Mar 2020 00:00:00 GMT

Over the years, this website has taken many forms. Initially, it was a Wordpress blog. Then is was a hand-rolled Sinatra app that rendered markdown pages. More recently I’ve blogged on Medium and at the time of writing, my website is a much simpler Sinatra app.

A few months ago I had an ongoing problem with medium which lasted about three months. I got a new Monzo card and medium couldn’t charge it. Although none of my articles were behind the paywall, it did mean that I couldn’t read other people’s paywalled articles. And even though I was happy to pay, I couldn’t. Eventually, after many many emails between me, Monzo and Medium, I involved Medium’s payment processor Stipe. Turns out that the problem was some bad data on their end. We resolved it, but only because I knew about stripe.

This whole experience left a bad taste in my mouth, and like a lot of other people it feels like time to move the canonical version of my writing onto a platform that I own… my own website.

At the same time, I’ve also become frustrated with my website. Considering what it does, it’s most definitely over-engineered. It’s not fun to play with any more, and I seem to spend most of my time on it updating dependancies. I also have to pay Heroku to keep it running.

Time to simplify things, then. I need a static site.

Why a static site?

If my site is just HTML and CSS then it’s easy to change, even if I’ve not touched it in years. There are no complex mental models to remember, no dependancies to manage, no security vulnerabilities to patch. I can also deploy it anywhere. I’m not reliant on any specific third parties. Static sites are also web scale by default when hosted in the right place.

So that’s my starting point… plain old HTML and CSS, deployed to Github Pages. When I want to write a new article I just make an HTML page. Simple.

But I also want to enjoy writing articles, which probably means writing in markdown.

So a static site generator is the obvious choice. All the cool kids are using Gatsby and Hugo, but after spending some time with both I think Jekyll is the best option for me. It’s simple, is battle-tested and is very very stable.

Before going any further with the tech, I need some values and principles to guide my decisions.

Values

After some time with a pen and paper, these seem appropriate:

Simple
Beautiful
Authentic
Content-first

Engineering Principles

Based on these values, I’ve pulled out some principles to guide my decisions on tech stack:

As few dependencies as possible (both build-time and run-time dependancies).
Use defaults wherever possible.
Write as little code as possible.
Do not over-abstract. Avoid fallbacks, polyfills and hacks.
Bake accessibility in.

I’ll come back to these regularly.

Jekyll Plugins

It’s tempting to install a whole bunch of plugins – there are some great ones out there. But every plugin is a build-time dependancy, so I’ve settled on just three.

Optional Front Matter. This makes the front-matter optional, obviously. I want it so that my HTML pages don’t need any front matter.
SEO Tag. This adds a bunch of SEO-related meta tags in a pretty intelligent way.
Redirect From. This lets me set up redirects in a super-intuitive way. I can crate an empty page or post, specify the redirect in the front matter and be done with it.

But what about dynamic stuff?

My current website has some dynamic stuff. The only bits I still care about are my reading list and highlights. My medium highlights are pulled in via their private API and cached in Redis.

My pocket items and medium recommendations work a bit differently. When I clap for an article on medium or archive one in pocket IFTTT sends a request to an endpoint which stores the details in a Postgres database which the Sinatra app can access.

On reflection, I don’t care about the highlights right now.

But I definitely want to retain the likes from Pocket and Medium. I don’t want to maintain a Postgres database though.

Enter Airtable. I can have IFTTT create a record in Airtable whenever I clap for a medium article or archive a pocket item.

Although this means I’m dependant on Airtable for this part of my website, I’m okay with that because it’s not a core part of my site: if airtable goes down or kill my account then 🤷‍♂️. The advantages well outweigh the overhead of managing my own server and database. Also…

It’s easy to pipe data into Airtable from all sorts of places.
It’s easy to edit data in airtable, especially because I use it a bunch anyway.
It has a very nice API.

There is one problem, though. For my javascript to access this data it needs my Airtable API key. I can’t just bung that in my code because then everyone would have it. This is something Netlify’s lambda functions are great at: they can act as an intermediate layer between my client-side javascript and the Airtable API.

Netlify also makes a lot of sense for hosting: it has some bells and whistles Github Pages lacks.

So here’s where we’re at so far…

Core Stuff

Just HTML, CSS and Markdown.
Jekyll (with a couple of plugins).
Netlify for hosting.

Reading List Stuff

Airtable - data store.
Netlify Functions - accessing Airtable.
IFTTT - piping stuff into Airtable from elsewhere.

What about the writing experience?

For the most part, I’m happy to write locally in iA Writer or VSCode. For writing on-the-go, Forestry seems like the best option. I’d dearly love to find a git-based-jekyll-compatible editor that works like Ghost or Medium, but that can wait.

With these decisions made, it took a surprisingly small amount of time to get all this wired up. Less than two hours. That’s the value of simplicity, I suppose.

Business Process & Tooling

Thu, 05 Mar 2020 00:00:00 GMT

Little Thing — Mocking External Services on Ruby

Wed, 04 Mar 2020 00:00:00 GMT

Breaking Down Problems: It’s hard when you’re learning to code

Wed, 14 Nov 2018 00:00:00 GMT

Little Thing — Value Objects in Ruby

Mon, 05 Nov 2018 00:00:00 GMT

Little Thing #2 — Speeding up ZSH

Thu, 09 Aug 2018 00:00:00 GMT

Little Thing #1 — How do RSpec Matchers Work?

Thu, 12 Apr 2018 00:00:00 GMT

Little Things

Mon, 02 Apr 2018 00:00:00 GMT

Synchronising Git Merges with Slack

Tue, 19 Dec 2017 00:00:00 GMT

The Definition of Done: What does “done” actually mean?

Tue, 19 Dec 2017 00:00:00 GMT

Add Starred Slack Messages to Things 3

Sun, 26 Nov 2017 00:00:00 GMT

Where are the good Mobile Networks?

Mon, 19 Jun 2017 00:00:00 GMT

The Definition of Done: What does "done" actually mean?

Mon, 19 Jun 2017 00:00:00 GMT

Scrum defines the definition of done in pretty simple terms: it’s the acceptance criteria that are common to every single user story. For scrum teams, it’s really important to have a solid definition of what “done” means. They work in sprints, and need some way of deciding whether a user story is actually finished. It’s no good ending a sprint with a user story that meets all its acceptance criteria, but had no code review, hasn’t been tested and isn’t deployable. Such a story is clearly not done. Scrum teams solve this by strictly defining “done”. In this case, in addition to meeting the acceptance criteria, the story must also:

Have had a code review.
Have been tested.
Be immediately deployable.

If this isn’t the case at the end of the sprint then it isn’t done - we can’t count it’s story points towards the sprint velocity and it needs to go on the backlog for the next sprint planning session.

What does “done” actually mean, though?

Is a new feature “done” when it’s in production and being used by customers? It might be. Equally, it might not. Have we published the changelog? Have we emailed our customers to tell them about the feature?

When is a technical improvement or refactoring “done”? We certainly don’t want to email our customers about it, and we probably don’t want to add it to the changelog.

The definition of “done” depends on the task.

Some teams get around this problem by having multiple definitions of “done” - one for bugfixes, another for features, another for technical tasks, and so on.

At CharlieHR, this seemed overly complex. We don’t use scrum, and we don’t work in iterations. But we still need a way to remind ourselves of the stuff that should be done before a task is considered finished. So we invented a checklist.

Our DoD at Charlie

We use two definitions. The first is ready to merge. Everything in this checklist needs to be ticked off before the pull request is merged to the master branch. The second is actually done. Everything in this checklist must be ticked off before the card is moved to the Done column on our task boards.

It’s worth noting that these rules apply to every single work item that goes through our task boards, so long as it involves code. Whether it’s a large user story with multiple dependencies or a tiny bugfix, the person doing the work is expected to run through these checklists.

That doesn’t mean that everything on the checklists has to be ticked off for every work item, though - a tiny technical improvement is unlikely to need a marketing email written about it, for example. It does mean that everything in the checklist must be considered for every work item. We trust our engineers to use their judgement.

While you’re reading the DoD below, bear in mind…

We use Trello for our task boards. Most teams have columns for backlog, next up, in progress and done. New features and user stories are represented by trello cards on a team backlog.
Technical improvements and exceptions begin life as GitHub issues. These get a trello card on the backlog when they are assigned to or picked up by a team. Bugs live in Sifter, and get a trello card when they’re assigned to a team.
The order in which the items below are considered is irrelevant, so long as they have all been considered.

I’ve made notes in italics, since some of the items need a bit of explanation.

Checklist 1: Ready to Merge

Kickoff done and requirements clear. Kickoff Document stored on Drive. This is where we define our acceptance criteria and the scope of a new feature. Most non-trivial user stories require this, and the kickoff for an epic may spawn multiple, smaller, inter-dependant user stories. Bugfixes don’t normally need a kickoff: it’s down to the product manager and engineers to decide whether a work item needs one. The kickoff document is just the record of the discussion, and contains sufficient acceptance criteria to get the thing out.
Implementation Plan written and reviewed. This is something we’re trying out. For non-trivial work items, engineers discuss and plan the technical solution. This usually involves whiteboarding and scribbling on bits of paper. The implementation plan is a summary of that thinking and is available for engineers from other teams to review. We’re hoping this will help catch architectural and system design problems early. For technical improvements, this discussion has usually happened on the associated github issue already.
DPIA Form Completed. Do we need to do a Data Protection Impact Assessment?
Card on Trello, properly labelled, sized and PR/Issue linked (mandatory). Before a trello card is picked up it must be labeled, have a T-Shirt size and have any associated stuff (kickoff doc, implementation plan, github issue, sifter issue etc) attached to it. Once a pull request is open, this (or these) should be attached too.
Pull Request open and properly labelled (mandatory). We open a PR after the first commit to a branch. Early comments on the PR save time and help share knowledge between teams.
Acceptance criteria met. Obviously. If changes to the requirements have been agreed with the product manager, have they been noted on the kickoff document or trello card?
Unit tests written.
Functional specs written.
Documentation folder reviewed for any changes/additions. We have a directory containing markdown files that describe the design patterns and conventions we use.
Environment variables documented, added to secrets manager and present in staging & production environments.
Analytics considered. Do we need to track user behaviour, and how should that be reported to our analytics tools. For larger work items, this is usually specified in the the kickoff doc.
“What’s New“ section updated. If this is a new feature, we may want to tell our users about it.
l18n reviewed. All our copy (including microcopy) should live in locale files.
Security & Data Protection Review (mandatory). We take security seriously. Have we made a deliberate and methodical check that this doesn’t introduce any obvious security or data protection issues. This is particularly important for small bugfixes, since they may not have had detailed planning.
Code Review from at least one other (mandatory). We strictly enforce this with our GitHub settings.
CodeClimate clear of errors. As well as tracking our test coverage, we run static analysis tools like rubocop and ESLint against out changes. We’re still tweaking the rules for these tools to suit our in-house style.
Feature Branch green on CI (mandatory). We also enforce this. You cannot merge to master with a red build on your feature branch.

Checklist 2: Actually Done

Merged to master and feature branch deleted (mandatory). The master branch is automatically deployed to our staging environment. I wrote about our merge process earlier.
Related GitHub Issues closed or updated.
Sifter, Appsignal, and #tech-support issues closed 🏁. We have a slack channel where people can raise technical issues. If a work item resolves or relates to one of these, it should be marked. This mostly applies to tiny bugfixes. Resolved bugs and exceptions should be closed in Sifter and Appsignal, respectively.
Manually tested on staging environment (mandatory). We don’t have dedicated QA people, so engineers and product managers conduct acceptance and exploratory tests. For work items that carry significant business or technical risk, we’ll draft in people from across the company to help.
Deployed to production with no obvious errors/exceptions (mandatory). Once a PR is deployed, we expect our engineers to keep an eye on the slack channel that shows our exceptions. If the deploy causes a flurry of them, it should either be rolled back and fixed or they should be addressed in a new PR before the work item can be considered done.
Release email sent. We send a company-wide email for all non-trivial releases.
Marketing document updated. If the work item is a new feature or important bugfix, it’s recorded in a spreadsheet. The marketing team refer to this when sending updates to our users.
Usage metrics checked/set up. Have we checked that data is coming through correctly? Do we need to update any formulas or one of our Geckoboard dashboards?
Help pages updated. If we’ve added a feature, changed the way something works or updated the UI, we might need to update our user guides, help documentation and canned responses in intercom.
FINALLY, card moved to “done” on trello (mandatory).

Mandatory Items

You’ll notice that some of the items are marked mandatory. Those must be done for every single work item. No exceptions. For a scrum purist, these are the only things that should appear in a Definition of Done. For us (right now), they are probably the least useful items on the list - they’re all important enough that we’d remember to do them even if we didn’t have a checklist!

At the moment, we’re deliberately keeping our mandatory items to a minimum, though we have discussed making more stuff mandatory. As we continue to evolve our process, I expect we’ll add items to support our current engineering goals. If we were focussed on improving our unit test coverage, we might include an item that says “all new models and POROs must have an associated unit test”. If we were focussed on improving the quality of our codebase, we might insist that “every pull request must improve the CodeClimate quality rating”. We might even decide to make proof of business value a prerequisite for “done”.

Currently though, we are focussed on building an awesome product, and while most pull requests include unit tests and quality improvements, it doesn’t make sense to mandate that just now. Our “Definition of Done” is designed to help us work better and faster, and will change and evolve alongside our business goals.

Six awesome services I discovered last year

Thu, 18 May 2017 00:00:00 GMT

DigitalOcean, DNSimple and Terraform: A very short introduction.

Mon, 24 Oct 2016 00:00:00 GMT

Agile Adoption Patterns

Thu, 30 Jun 2016 00:00:00 GMT

Good Slide Design

Sat, 23 Apr 2016 00:00:00 GMT

Slack for Enterprise

Thu, 10 Mar 2016 00:00:00 GMT

A Standard Software Toolset for Business?

Sun, 06 Mar 2016 00:00:00 GMT

Finding a Good Colour Palette through Exploration

Wed, 02 Mar 2016 00:00:00 GMT

Why do I teach?

Thu, 25 Feb 2016 00:00:00 GMT

Automating and Outsourcing

Sat, 20 Feb 2016 00:00:00 GMT

Collaborating on a Project

Mon, 04 Jan 2016 00:00:00 GMT

Effective Meetings

Fri, 18 Dec 2015 00:00:00 GMT

My Students have Forgotten How to be Curious

Tue, 03 Nov 2015 00:00:00 GMT

Evaluating Training and Learning

Mon, 26 Oct 2015 00:00:00 GMT

Getting Things Done

Sat, 29 Aug 2015 00:00:00 GMT

The Psychoactive Substances Bill 2015

Sat, 25 Jul 2015 00:00:00 GMT

The Changing Face of Software Testing

Wed, 22 Jul 2015 00:00:00 GMT

Delivering Business Value with Kanban and Validated Learning

Tue, 17 Mar 2015 00:00:00 GMT

Blogging with Evernote and Ruby

Thu, 26 Feb 2015 00:00:00 GMT

Replacing Bash with ZSH on OSX

Thu, 26 Feb 2015 00:00:00 GMT

Agile Feedback Loops

Tue, 24 Feb 2015 00:00:00 GMT

Writing Testable Code

Tue, 24 Feb 2015 00:00:00 GMT

On Sass and Other CSS Preprocessors

Sun, 04 May 2014 00:00:00 GMT

Controlling the Rag with Redcarpet

Sun, 04 May 2014 00:00:00 GMT

Good typography is about the accumulation of small improvements. As Mark Boulton puts it:

“Good typographic design — on the web, in print; anywhere, in fact — relies on small, measurable improvements across an entire body of work”

I’ve implemented several typographic improvements in my Ruby-based website using a custom Redcarpet renderer that automatically fixes common typography issues.

The Problems We’re Solving

Orphans - Single words hanging alone on the last line of a paragraph
Short phrase breaks - Emphasized phrases breaking across lines
Awkward line breaks - Lines breaking after prepositions, dashes, or short words

Custom Redcarpet Renderer

Here’s how I implemented these fixes:

Preventing Orphans

def paragraph(text)
  # Replace the space between the last two words with a non-breaking space
  text.gsub!(/\s+(\S+)\s*$/, '&nbsp;\1')
  "<p>#{text}</p>"
end

Keeping Short Phrases Together

def do_not_break_string(text)
  # Keep short emphasized phrases together
  text.gsub!(/<(em|strong)>([^<]{1,15})<\/(em|strong)>/) do |match|
    match.gsub(' ', '&nbsp;')
  end
  text
end

Preventing Breaks After Short Words

def avoid_breaking_after_short_words(text)
  # Complex regex to identify words that shouldn't be broken
  text.gsub!(/(\s)(a|an|and|as|at|but|by|en|for|if|in|of|on|or|the|to|vs?\.?|via)(\s)/i) do |match|
    "#{$1}#{$2}&nbsp;"
  end
  text
end

The Results

These small improvements compound to create noticeably better text rendering:

Fewer orphans - Paragraphs end more naturally
Better emphasis - Short emphasized phrases stay together
Smoother reading - Fewer awkward line breaks interrupt the flow

Implementation Details

The custom renderer processes Markdown content before it’s converted to HTML, applying these typographic rules automatically. This means I can write naturally in Markdown while getting professionally typeset results.

Typography Principles

The key insight is that good typography happens at the micro level. Each individual improvement might seem small, but together they create text that’s:

More readable - Fewer distractions from poor line breaks
More professional - Attention to typographic detail shows craftsmanship
More accessible - Better text flow helps all readers

Conclusion

Controlling the rag (the uneven right edge of left-aligned text) and preventing orphans are foundational typography skills. By automating these improvements in my Redcarpet renderer, I ensure consistently good typography across all my content.

These techniques work especially well on the web, where we have tools like non-breaking spaces to fine-tune text rendering without sacrificing the flexibility of HTML and CSS.

A Pretty Readability Archive with Ruby and CSS

Sun, 20 Apr 2014 00:00:00 GMT

I’ve always found it interesting to see what other people read. Not just the things that they share on twitter, but the articles they read on a daily basis.

I decided to build a web application to display my Readability bookmarks using Ruby, Sinatra, and CSS transitions to create an interactive card-based layout.

The Technical Implementation

The application follows these key steps:

Environment variable setup - Secure authentication credential storage
Readit gem integration - Ruby library for the Readability API
XAuth authentication - Secure API authentication
Bookmark fetching - Retrieving archived articles
Interactive card display - CSS 3D transforms for flippable cards

API Integration

Using the Readit gem, I configured the Readability API connection:

# Configure the Readit API
Readit.configure do |config|
  config.consumer_key = ENV['READABILITY_KEY']
  config.consumer_secret = ENV['READABILITY_SECRET']
end

# Authenticate via XAuth
client = Readit::Client.new(
  oauth_token: ENV['READABILITY_TOKEN'],
  oauth_token_secret: ENV['READABILITY_TOKEN_SECRET']
)

# Fetch archived bookmarks
bookmarks = client.bookmarks

Interactive Card Design

The CSS creates an engaging card-based layout where each bookmark has:

Front face - Title and background image from the article
Back face - Article excerpt and metadata
Flip animation - Smooth 3D transform on hover

The cards use CSS 3D transforms to create a flipping effect that reveals additional information about each article when you hover over them.

Key Features

Responsive design - Cards adapt to different screen sizes
Visual appeal - Each card shows the article’s featured image
Rich metadata - Article excerpts, publication dates, and sources
Smooth animations - CSS transitions for polished interactions

Future Improvements

Potential enhancements I’m considering:

Infinite scrolling - Load more bookmarks as you scroll
Responsive grid - Replace fixed-width layout with flexible grid
Filtering - Sort by date, source, or tags
Search functionality - Find specific articles quickly

Reflection

This project combines API integration, responsive design, and interactive CSS to create something genuinely useful. It’s a great example of how modern web technologies can transform simple data into engaging experiences.

The combination of Ruby for backend processing and CSS for frontend interactions creates a fast, visually appealing way to browse through saved articles.

From RVM to rbenv

Tue, 08 Oct 2013 00:00:00 GMT

I recently switched from RVM (Ruby Version Manager) to rbenv for Ruby version and gem management. This isn’t so much of a ‘howto’, as a dump of my bash history for anyone looking to make a similar transition.

Why I Left RVM

RVM had several issues that frustrated me:

Complicated gem and Ruby version management - The system felt overly complex
Unclear storage locations - I never knew where gems and Ruby versions were actually stored
Confusing gemset commands - The gemset system was hard to understand and manage

Why rbenv is Better

rbenv offers several advantages:

Simpler to understand - The system is more transparent
Works well with Bundler - Better integration with modern Ruby workflows
Easier project-specific Ruby version management - .ruby-version files just work

The Migration Process

Here’s the process I followed to switch:

Completely remove RVM - Clean out all RVM-related files and configurations
Clean out old Ruby and gem installations - Start fresh
Install rbenv via Homebrew - Use the package manager for easy installation
Install desired Ruby versions - Install 1.9.3 and 2.1.4 (the versions I needed)
Set up default gems - Install commonly used gems
Install rbenv plugins - Add rbenv-bundler for better Bundler integration

The Result

The goal was to create “a decent local ruby environment that I actually understand.” rbenv delivers on this promise by being:

Transparent - I can see exactly what’s happening
Simple - No complex gemset management
Reliable - Works consistently across projects

Key Commands

The most important rbenv commands I use daily:

rbenv versions          # List installed Ruby versions
rbenv global 2.1.4      # Set global Ruby version
rbenv local 1.9.3       # Set local Ruby version for current directory
rbenv rehash            # Refresh rbenv shims

The switch from RVM to rbenv was one of the best development environment decisions I’ve made. If you’re frustrated with RVM’s complexity, rbenv is definitely worth considering.

New Job, New Website

Wed, 02 Oct 2013 00:00:00 GMT

I’ve recently transitioned from being a designer to a Ruby developer in London. As part of this change, I decided to build a completely custom website using Sinatra rather than relying on existing platforms.

Why Build Custom?

After trying various blogging platforms, I couldn’t find one that met my specific requirements:

Writing in Markdown - I wanted to write everything in Markdown
Full control over HTML and CSS - Complete creative freedom
Easy image management - Simple way to include images
Understanding all the code - I wanted to know exactly how everything worked

The Technical Setup

The website is built using a custom Sinatra application with several key features:

Static assets compiled locally - CSS and JavaScript are processed before deployment
Custom Redcarpet renderer - Markdown is parsed with custom formatting rules
Special tag system - Images and gists can be inserted using custom tags like {{image: 1}}
Pygments syntax highlighting - Code blocks are highlighted using Pygments.rb

Deployment

The site is deployed to Heroku with New Relic monitoring to prevent the app from going to sleep. This ensures fast loading times even during periods of low traffic.

Custom Styling

I’ve implemented custom styling for all standard Markdown elements:

Lists - Both ordered and unordered with custom styling
Blockquotes - Styled for emphasis and readability
Code blocks - Syntax highlighted with clean typography
Tables - Responsive and well-formatted

Reflection

This project reflects my journey from designer to developer. Rather than using off-the-shelf solutions, I prefer building custom tools that give me complete creative and technical control. The site was quickly developed and deployed, proving that custom solutions don’t always require extensive development time.

The key is understanding your exact requirements and building just what you need, nothing more.

MoD Email Subjects with AppleScript

Fri, 28 Jun 2013 00:00:00 GMT

The work I do with the RAF and Army requires me to send emails with the date and security classification included, like this: “20130628-The Subject-U”.

I must do this at least 30 times a day, and earlier on I was that fed up with copy/pasting dates that I decided to write a script to do it for me. I did try this once before, but Mail.app’s API wasn’t very robust at the time and the action relied upon simulating keypresses which wasn’t exactly reliable.

The following script adds the date and PM to the subject of the foremost Compose Mail Window. It’s a little smarter than my previous attempt too, in that it replaces the date if it’s already there and leaves the PM alone if it exists already.

This one opens a reply to the selected message, with the “Re:” in the right place:

Using Applescript is awkward to say the least - Russell Beattie puts it quite well:

Using AppleScript is like being tied down in a black leather gimp-suit at a dominatrix convention, and losing the safety word… The syntax is like Erlang and ancient Greek got somehow mixed together with Visual Basic, and was translated back into English by mentally-challenged ESL students

I did try to make a plugin for Mail.app to add some buttons to the menubar, but after discovering how difficult it is working with Mail.app’s undocumented API, I gave up and created a Service instead.

Despite AppleScript’s quirks, it’s still the most reliable way to automate Mac applications, especially when you need to interact with specific UI elements like email compose windows.

What is Good Design?

Mon, 21 Jan 2013 00:00:00 GMT

The UK Government Digital Service (GDS) has created something special with gov.uk. Moving away from skeuomorphic design trends, they’ve focused on content-first, accessible design that makes government information truly usable.

As John Gruber noted about skeuomorphic design:

“On retina displays… these techniques are revealed for what they truly are: an assortment of parlor tricks”

The GDS approach demonstrates that good design doesn’t need visual tricks. Instead, it comes from:

Content-focused layout that prioritizes information over decoration
Thoughtful typography including their excellent adaptation of the Transport typeface
Accessibility ensuring government services work for everyone
Flat design that focuses on usability rather than visual effects

Andy Budd’s observation rings true here:

“The best designers and developers rarely have more talent. They simply have more time.”

This echoes Teller’s insight about magic:

“Sometimes magic is just someone spending more time on something than anyone else might reasonably expect.”

The gov.uk website succeeds because the team invested time in getting the fundamentals right: clear typography, logical information architecture, and user-centered design principles.

Good design, it turns out, is less about flashy effects and more about well-designed content, typography, and layout—combined with the time to experiment and refine until everything works seamlessly together.

A Simpler Responsive Grid

Tue, 05 Jun 2012 00:00:00 GMT

After making use of various complicated CSS grid systems, I’ve been using a simple percentage-based grid for the last year or so. It’s based on a 1000 pixel wide container with 63 pixel columns and 20 pixel gutters. The outside gutters at the extreme left/right are 12 pixels to produce a nice round number.

By using a 1000 pixel wide container, the maths is easy when using percentages. each column is 6.3%, gutters are 2% and so on…

By setting a width on the container of 100% and a max-width of 1000 pixels, and thereafter using percentages for all widths, everything resizes nicely:

#container {
    margin: 0 auto;
    max-width: 1000px;
    width: 100%;
  }

  #my-box {
    width: 14.6% /* Two columns wide - (2 * 6.3)+2 */
    margin-left: 1.2% /* Covering the first two columns */
  }

I’ve knocked together a quick example page (code) that shows the columns. One problem with percentage-based widths is that because of the box model, any borders or padding will be added onto outside of the box. Obviously this can be a drama if you’re using pixels to declare your borders and padding.

The easy solution to this is the box-sizing property:

#my-other-box {
    width: 31.2% /* Four columns wide */
    margin-left: 9.5% /* Covering columns 2 to 5 (1.2 + 6.3 + 2) */

    box-sizing: border-box;
    border: 2px solid red; /* will be rendered inside the box */
  }

Although this property isn’t supported in IE7 and below, it’s a useful way to control the box model and make responsive design easier.

Danny Smith - Articles

How my personal video platform works

1. Opening the menubar app

2. Pressing record

3. During Recording

4. Pressing Stop

5. When recording’s finished

Healing

Restitching

Audio Enhancement

Thumbnail candidates

Generating video variants

Generating storyboard images

Suggested edits

Transcription & Subtitles

Suggested title and description

So where do we end up?

On Disk

Footnotes

An actual homepage for this site (finally)

Footnotes

Introducing my very own Loom

The Four Moving Parts

The macOS recording app

The UI while recording

The viewer-facing surface (a quick tour)

The admin app, a lightning tour

Wrapping up

Vibe coding an iOS app to publish notes here

There’s gotta be a chrome extension for that?

Vibe coding my first personal iOS app

How it works

Getting notes to GitHub

Building Apps for One

Making this Astro site more Agent-Friendly

Existing “agent friendly” features

Markdown versions of my content

An llms.txt index

JSON-LD

Auditing for Agent Friendliness

Better Agent-Friendliness

1. Update robots.txt

2. Have every page point at llms.txt

3. Serve markdown to UAs asking for it

4. Advertise the index Even More

5. Make it easier to discover markdown versions

6. Turn meta-refresh redirects into propa HTTP redirects

So where did we end up?

Wrapping up

Speeding up Astro builds and improving deployment

Speeding up the Astro build on GitHub

Fix 1 — Cache node_modules/.astro

Fix 2 — Add a file-cache to OG image generation

Fix 3 — Run Check and Build in parallel and only deploy after both

Fix 4 — Stop npx re-downloading the Vercel CLI

So how much faster did things get?

Adding some light Vercel config

Dealing with .well-known files

Wrapping up

Some Work on this Site

I made a video platform

Code Blocks & Tables

Inline Styles, Footnotes, Lists & Callouts

Lists that breathe

Slightly Better Callouts

New Fence-Based Components

Markdown Blocks

File Trees

A Fourth Typeface

Wrapping Up

Footnotes

Introducing Astro Editor

What is it?

Why?

But why?

Where we at now?

So what’s Next?

Like & Subscribe plz

Quite The Journey

Moving this site to Astro

An `llms.txt` index

1. Update `robots.txt`

2. Have every page point at `llms.txt`

Fix 1 — Cache `node_modules/.astro`

Fix 4 — Stop `npx` re-downloading the Vercel CLI

Dealing with `.well-known` files