wrkstdy · blog

plugh, tracking voice and tone

Tue, 27 Oct 2026 00:00:00 +0000

Two weeks ago, alongside the first post here, I started a file called notes/style-guide.md. It was a scratchpad: a handful of rules about dashes, slashes, and the word “markdown”, and two of them ended with “Common slip of mine.” It wasn’t a style guide yet, just a list of things I either got wrong or disagreed with in how AI wrote them.

Admittedly, most of what I write here now involves AI, either drafting from my notes or reviewing what I wrote. The rules matter in both directions: they keep me honest when AI reviews a draft, and they guide it when it writes off of my notes. That’s where the scratchpad started to strain. A notes file is easy for me to keep in my head. For AI, it either gets pasted in whole every time, or it doesn’t get read at all.

Two things pushed it from a notes file to a tool. I knew I’d have other projects needing copy soon, each with its own voice and readers, and a scratchpad in this repo wasn’t going to follow me there. And I’d been reading Little Plains’ Agentic Systems Are the Future of Brands. It describes a brand kit written for people and agents alike, with a readme that points each job at the files it needs. The line that stuck with me: “It doesn’t need every file every time, but it does need to know where to start.” I wanted a practical way to apply that kind of focused prompting to my own writing, across this blog and whatever came next.

So I built plugh: a small tool for keeping voice and tone rules in pieces, and handing AI only the pieces that apply to what it’s writing. This post covers why I split the guide up, how the pieces get routed, the checks that catch my usual slips, where those checks still get it wrong, and how a draft gets from AI to done.

One file doesn’t fit every page

The site has more than one kind of writing. A blog post is for a developer who found it through a search and skims the headings. A recipe is for someone standing at the counter with wet hands who wants succinct steps. A front matter description is one or two sentences on the homepage.

Some rules hold for all of them: write as “I”, say the specific thing, explain the why. But “open on a concrete moment” is wrong for recipe steps, and “one step per line, amounts first” is wrong for a post. One long guide means every piece of writing carries rules for every other kind.

Splitting it up helps in two ways. For me, it means I can write a rule for the situation it’s actually about, instead of hedging it to cover every kind of page. For AI, it keeps the context lean and focused: it reads the rules for what it’s writing, and nothing else to weigh against them. A recipe rule can’t pull a blog post off course if it never gets loaded.

I’ll admit I never got as far as the one big file. The scratchpad was still small when I split it up. But between the Little Plains piece and knowing that every rule rides along with every request, paid for in tokens each time, it seemed worth tackling before the guide grew rather than after. (so no dead end here, just a cost I decided not to wait for)

Chunks, and a router

In plugh, each rule set is a chunk: a short markdown file in voice/, like voice/punctuation.md or voice/recipe-steps.md. Each rule in a chunk says the rule, why it exists, and what to do when unsure. The “when unsure” line ended up being the part I like best, because it’s what lets the rule stretch to a case I didn’t think of.

A voice.yaml at the project root routes chunks to content by path. Here’s the part of mine for blog posts:

types:
  blog:
    match: content/blog/
    always:
      - voice-core
      - punctuation
      - word-choice
      - blog-post
    if_relevant:
      - photo-captions
    budget: 1500 # words

always chunks load every time. if_relevant chunks show up as a one-line summary, and only get loaded when they apply, like the captions chunk for a post that has photos. A type doesn’t have to be a folder, either. The front matter description is a type of its own, routed by the job instead of a path.

Running go tool plugh context on this post prints exactly what AI reads before writing it: who’s writing, who it’s for, and the 4 chunks.

The full output of go tool plugh context for this post

# Voice for blog (content/blog/)

Follow these chunks. Where they're silent, follow their "When unsure" lines.

## Writing as me

Steven, a developer writing a personal log. Works things out in public, keeps the dead ends, and would rather be useful than impressive.

## Writing for curious-dev

A developer who found the post through a search or a link. Knows the basics, hasn't solved this exact problem, and wants the choices and the reasons more than a tutorial. Skims headings first.

<!-- chunk voice-core, from voice/voice-core.md -->
# Voice core

Everything on wrkstdy is me talking to one reader. These are the defaults every other chunk builds on.

### First person, plain words

Write as "I", the way I'd explain it to a friend across the table. Prefer the plain word over the clever one. "We" is for me and AI working on something together, and only when that's who did it.

Why: the site is a personal log, not a product. Polish that hides the person defeats the point. A "we" that means me and AI is honest about how the work happened; any other "we" blurs who's talking.
When unsure: read the sentence out loud. If I wouldn't say it, rewrite it. If "we" could mean the reader too, name who did it.

### Specific over general

Name the thing: the tool, the number, the place, the moment. "5 MB straight off the phone" beats "large files".

Why: specifics are what make a post mine instead of generic.
When unsure: ask "which one?" of every general noun, and answer it.

### Explain the why

When I made a choice, say why, including the options I didn't take.

Why: the reasoning is usually the useful part for a reader, and the part I want to remember later.
When unsure: if a paragraph only says *what* happened, it's probably missing a *because*.

### Candid, a little self-deprecating

It's fine to admit a mistake, a dead end, or that something took longer than it should have. Light humor at my own expense, not at anyone else's.

Why: honesty about the process is the reason to read a dev log at all.
When unsure: poke fun at me, never at a person or a team.

### Stay humble

Present what I did as what worked for me, not the one right way. Say where my experience runs out, and leave room for the reader to know something I don't.

Why: I'd rather be useful than impressive, and a post that sounds like it has every answer is harder to trust.
When unsure: if a sentence tells the reader what they *should* do, check whether "what I'd do" is closer to the truth.

<!-- chunk punctuation, from voice/punctuation.md -->
# Punctuation

### Em dashes are a spaced ---

Write `word --- word`. goldmark's typographer turns `---` into an em dash and `--` into an en dash, and an en dash is for ranges, not breaks in a sentence.

Why: it's a common slip of mine, and the two look nearly the same in the editor.
When unsure: if the break could be a comma or parentheses, it probably should be.

### Throwaway asides

All lowercase, no closing punctuation, in parentheses: `(spoiler: this still took just an afternoon, maybe just a longer one)`. If an aside runs to more than one sentence, use normal capitalization inside it. An aside can sit inside a sentence or stand on its own between two, in the same format either way.

Why: a throwaway aside should read like one, quieter than the sentence around it.
When unsure: if the aside is important, it isn't an aside. Make it its own sentence.

### Italics for stress

Use *italics* on the one word I'd lean on when speaking. Not bold. Italics also mark a term the first time it's defined, like *chunk*.

Why: it's how I emphasize out loud; bold reads as shouting. A new term gets the same lean, once.
When unsure: one stressed word per paragraph, at most. A term is italic only where it's defined, not after.

### Oxford commas

In a list of three or more, put a comma before the "and" or "or": "dashes, slashes, and the word markdown".

Why: it's how I punctuate, and it keeps the last two items from reading as a pair.
When unsure: a pair that's one thing, like "salt and pepper", counts as a single item. That's why this check is a warning.

<!-- chunk word-choice, from voice/word-choice.md -->
# Word choice

### "Or", not a slash

"Hugo or 11ty", not "Hugo/11ty".

Why: a slash makes the reader decide what it means (and, or, either).
When unsure: paths, URLs, and fractions are fine; this is about words.

### "markdown" is lowercase

Always, including at the start of a list item. (At the start of a sentence, rephrase.)

Why: markdown is an idea, plain text with a little punctuation for structure, more than any one spec. CommonMark, GitHub's flavor, and goldmark all disagree on the edges, and I'm writing to the idea.

### Project names keep their casing

A lowercase name like plugh or tributary stays lowercase, even at the start of a sentence or a title.

Why: it's the name as written; capitalizing it makes a different word.
When unsure: this is for names. A common word like markdown still gets rephrased.

### Numerals for counts

Anything counted or measured is a numeral: "6 warnings", "1,500 words". At the start of a sentence, rephrase.

Why: a numeral is easier to spot when skimming, and mixing "6" and "four" in one paragraph reads as a slip.
When unsure: if the number isn't the point ("one or two sentences", "a thing or two"), words are fine.

### "I have", not "I've got"

Why: a common slip of mine, and "I have" is plainer.

### "AI", not the tool's name

When describing how work was done, say "AI".

Why: the post is about the way of working, not the vendor, and tool names date fast.
When unsure: naming a tool is fine when the post is *about* that tool. That's why this check is a warning.

### Repetition on purpose

Deliberate repetition for emphasis is fine ("wasn't mine, not really"). Don't edit it out, but question it.

<!-- chunk blog-post, from voice/blog-post.md -->
# Blog posts

### Open on something concrete

Start with a specific moment or a candid admission ("After a recent layoff...", "Here's a little secret"), not a thesis statement or a definition.

Why: it's how my posts have always started, and it earns the reader's attention before asking for it.
When unsure: cut the first paragraph and see if the second one is the real opening.

### Start broad, get specific

After the opening, give a short overview of what the post covers ("This post is a reflection on that, and a list of things I want to keep in mind..."), then cover it, one piece at a time. Each main topic gets a `##` heading; when a topic has parts of its own, break it up with `###` headings underneath.

Why: the reader knows where the post is going before the details start, and can decide which parts they need.
When unsure: every section should trace back to something in the overview, and everything in the overview should get a section.

### Headings carry the story

Short, plain `##` headings that tell the reader where the post is going ("Keeping a post and its photos together", "Resizing").

Why: posts get skimmed; the headings should work as a summary on their own.

### Show the work, including dead ends

When something was tried and dropped, say so and why ("I had a 1920px size at first, but...").

Why: the dead ends are often the most useful part for someone doing the same thing.

### Callouts for side points

A `> [!NOTE]` is for a side point the reader can skip without losing the thread. A few a post, at most.

Why: it lets a skimmer jump past it, and a post full of callouts has no thread left to follow.
When unsure: if the post doesn't make sense without it, it's a paragraph, not a callout.

### Close on what the reader takes away

End on what I hope the reader does or thinks differently, not on a recap.

Why: a recap repeats the post; a takeaway gives it a point.
When unsure: if the last paragraph starts with "In summary", rewrite it.

## Load if relevant

If a summary applies to what you're writing, run `go tool plugh chunk <id>` and follow it too.

- photo-captions: Alt text vs captions on photos in any section.

Who’s writing, and for whom

The router also names personas. For now — mine are “me”, “curious-dev”, and “home-cook”, each a few sentences long. Blog posts are written as me, for curious-dev. Recipes swap the audience to home-cook and keep the rest.

Someone reading a post and someone following a recipe want different things from the same site. Naming the reader once, up front, means the rules don’t each have to.

A budget on purpose

Each type gets a word budget, and plugh kit fails if a type goes over. The budget isn’t for the post. It’s for the rules: the always chunks plus the persona descriptions, which is everything AI reads before it writes a word. Blog posts get 1,500 words, and right now they use a little over 1,000.

Every word of rules is context AI has to hold alongside the actual task, and a guide that grows without limit stops being followed, by people and by AI. So adding a rule means checking whether an old one still earns its place.

Checks for the mechanical slips

Some rules are mechanical enough that a regex catches them. A chunk can carry checks in its front matter, and go tool plugh check runs them against every file a type covers. I've got is an error. Markdown with a capital M is an error. (the first draft of this post failed both, quoting them as examples) A slash between two words is a warning.

Note

Lowercase “markdown” is a choice, not a typo. To me, markdown is an idea, plain text with a little punctuation for structure, more than any one spec. CommonMark, GitHub’s flavor, and goldmark all disagree on the edges, and I’m writing to the idea, not one of them.

Warnings are questions, not orders. A tool name in a post is a warning because “say AI, not the tool” is the right default, but this post is about a tool, so naming it is fine.

Where the checks get it wrong

Running it against the rest of the site gives 0 errors and 6 warnings, and all 6 are wrong. Of those, 4 are the slash check, catching link text like [tdewolff/minify](https://github.com/tdewolff/minify), where the slash is part of a repo name, not a choice between two words. The other 2 are the Oxford comma check, which can’t tell a wire rack, salt and pepper them from a list.

Misses like these have had me question the mechanical checks more than once. A regex doesn’t know what a sentence means, and AI reviewing against the same rules does. But for rote checks, a regex is instant, costs nothing, and gives the same answer every time, which makes it far more efficient than asking AI. So I’m keeping them, as warnings wherever they’re guessing. Each wrong warning is another example of where the line actually is, and as they pile up, I expect they’ll point me toward something that works better.

One format, many projects

plugh is a Go module and a Claude Code plugin in one repo. The plugin has two skills: one loads the routed chunks before writing, and one reviews a draft against them without rewriting it.

Note

plugh is written for Claude Code, but the techniques aren’t tied to it. Small chunks of rules, routed by what’s being written, with checks for the mechanical slips, should carry over to other AI tools. plugh context just prints text, so anything that can run a command before it writes can read it.

plugh ships no rules of its own. The repo has a made-up example project to copy from, but the point is that the rules are yours.

I’m working on other projects with different voices and different readers, and none of this site’s rules belong there. What they can share is the format: the same chunks, router, and checks in each project — so the way I write rules down and hand them to AI carries over even when the rules themselves don’t.

tributary is one of them. It shows current conditions on the water for stream fishing in the US, so its readers are people using it, not developers looking to learn something. And even within tributary, a guide and the rest of the copy will want different rules, the same way a post and a recipe do here.

Working through a draft, one point at a time

A post starts with the write skill. AI loads the chunks for the type, works from my notes, and writes a first draft. For this post, it left marked gaps wherever a part needed something only I know, like the moment that started it or a dead end I hit, instead of making one up.

After that first draft, I run the review skill and work through what it finds one point at a time. I pick a spot, say what’s missing or what I’d say differently, and we change just that, then run plugh check before moving on. This post went that way: the point about keeping context lean, the budget, the Little Plains link, and this section were each their own pass.

Tip

Working through a draft is the perfect time to update the rules. When I make the same fix twice, or the review makes a call no rule covers, that’s a rule waiting to be written, and it’s easiest to write while I’m still looking at the content that needed it.

That’s just how I edit. Unless I’m making sweeping changes, I work on specific wording, a sentence or a paragraph at a time, and I didn’t want AI to change that.

Worth it, so far

It’s working. Even this post took fewer edits from me after the first draft than I’m used to.

It also gets better as I go. Along with its findings, the review lists the calls it made that no rule covers yet. Those are candidates, not findings, and I decide which ones become rules. Working through this post added 6: when “we” is fine, numerals for counts, lowercase project names, italics for a new term, asides that stand on their own, and when a callout earns its place. The next post starts with all of them.

It isn’t free, though. Every round of my workflow re-checks the draft with plugh, and that spends some tokens each time. Over a post’s worth of small passes it adds up, but it’s been worth it.

If you’re writing with AI and the drafts don’t sound like you, I’d start smaller than a style guide. Keep a list of the things you fix every time. That list is already most of a voice guide, and it’s one nobody else can write for you.

The new person's advantage, and caveats

Mon, 26 Oct 2026 00:00:00 +0000

After a recent layoff at #lastjob, a handful of people joined our team from another part of the company. They were smart, they were capable, and they showed up with strong opinions about how things should work.

What they didn’t show up with was much curiosity about how things already worked, or more importantly why they worked the way they did. This created friction that made it difficult to receive, triage, and apply those ideas.

I was on the receiving end of this one, and it’s stuck with me. It was also on my mind while reading Vikram Singh’s Increase your slope, which is written for new grads, but holds for anyone new to a team. One of their points is to get comfortable having opinions, and to do your homework and check them with a trusted person or two before taking them wider.

This post is a reflection on that experience, and a list of things I want to keep in mind the next time I’m the new person on a team. Here, I want to look at what it looks like when that homework — gaining context — gets skipped, why being new is still an advantage, and what the homework looks like.

Simplifying a cache key

Here’s the example I keep coming back to. We had an edge cache, and the cache key admittedly had a lot of dimensions in it. To someone new, that looks like a smell: too much cardinality, simplify it, an easy win to fix the hit rate.

But those extra dimensions came from features we’d introduced over time, like an existing user’s ecommerce plan or a visitor’s device type. They had widely varying levels of usage, and each one could change what the origin would send back. Just simplifying the cache key would mean some visitors might end up with a page that was meant for someone else, or a stale variant of the right one. (spoiler: nobody enjoys finding that out in production)

Whether every one of those differentiators still mattered was a fair question, but making that decision would need to involve stakeholders. The fact that they could matter was the context the newcomers were missing. They could describe the change they wanted, but weren’t telling us what the current setup was protecting and how that risk would be handled.

So the conversation never started from “is this protection still worth it?” It started from “why is this so complicated?”, and we spent our energy re-explaining instead of improving anything. This pattern repeated and got personal and political faster than I’d like to admit.

Being new is an advantage

I don’t believe being new means you shouldn’t have opinions or share ideas. Being new is a real advantage, and it’s worth saying so plainly.

You don’t know the patterns yet, so you don’t know which ones are “just how it’s done” and which are stale constraints.
You’re more willing to ask the obvious question everyone else stopped asking.
Teams go blind to their own friction. The new person still feels it.

Sometimes the question is as simple as “why is the hero image lazy loaded?” It was asked to understand, not to correct, and it was a real catch. The team that built the page had missed some of our requirements and conventions, and it took someone new to notice.

Sometimes it’s more fraught, like the blocking request for our experiments JS file, which we didn’t cache. It was posed as a mistake, but it exposed a lack of trying to understand how the system worked. That file had to vary on criteria our cache didn’t know about, down to the individual user. Caching it would have meant serving someone else’s experiments.

The difference wasn’t the question, it was how it was asked. The same lack of familiarity that lets you see the friction also hides the reasons behind it.

Context has to be earned

It helps to start by assuming good intent. Most weird-looking things are weird for a reason: an outage, a customer, a constraint, a person who left. Some of those reasons are still good. Some expired years ago and nobody noticed.

From the new seat you can’t tell which is which, and proposing a rewrite in week two costs trust even if you turn out to be right. Sometimes the context a decision was made under no longer applies, but you have to seek the context to know that.

Back to the cache key

The stakeholder conversation it needed took context and clout, and the newcomers had neither yet. So even a good idea couldn’t land on its own. Earning the context is also how you earn the standing to have the bigger conversation.

Their idea wasn’t wrong. A simpler cache key was worth wanting. But it came without the context of who it needed to go to, the stakeholders behind each of those features, or of the effort it would take to implement safely: checking each dimension, and rolling it out without serving anyone a page meant for someone else.

So the question was never whether they were right or wrong. It was who needed to be part of the decision, and what it would take to make the change safely. That made it a conversation with stakeholders, not solely an engineering cleanup.

Ask, but ask to understand

None of this means sitting on questions. We had a saying to encourage that: “there are no bad questions.” I want them asked, but framed as “help me understand why” instead of “why don’t we just.”

Note

“Just” can generally be considered a four-letter word. It carries a lot, and if you find yourself thinking it, take a step back and consider what it really means.

For myself, I want to make sure I learn the history before I propose a change. If the reason is still valid, it saves everyone a debate. If it’s expired, I’ll have the context to make the case and the trust to be heard.

Some pre-work

There’s a tool I like for checking whether I’m ready. George Heilmeier ran DARPA in the 1970s and wrote up a short list of questions for vetting proposed projects, now known as the Heilmeier Catechism. The one I’d borrow before suggesting anything new:

How is it done today, and what are the limits of current practice?

If I can’t answer that, I’m not ready to propose a change yet. Answering the first half is gaining context. Naming the limits is what turns a pitch into a case other people can weigh. And it’s exactly what was missing from the cache key conversations: the newcomers could describe their idea, but not “how it’s done today.”

Before I take an idea to anyone else, these are the questions I want to test it against myself:

Assuming good intent, why does this exist? What could it be providing?
What would it take for this to change? Who would need to agree, and what would have to be true first?

Spend it on curiosity

Newness is an asset that runs out, and I intend to use it the next time around. I want to be deliberate with it, though: spend it on curiosity, not conclusions. The conclusions will still be there in a few months, and they’ll be better than they would be otherwise.

Photos: transcoding and lazy loading

Mon, 19 Oct 2026 00:00:00 +0000

The site has two new sections: a journal, for photos and notes from trips, and recipes, where the first one is ssamjang wings. Both lean on photos, but the generator didn’t know what a photo was or how to handle them. Straight from the camera or phone they could be 5 MB or more, so dropping them in as-is wasn’t an performant option.

Going in, I knew it needed two things:

Configurable eager or lazy loading. Most photos are further down the page and can wait until you scroll to them, but one at the top shouldn’t. Which is which depends on where the photo sits, so it has to be set per photo.
Resizing and transcoding. Each photo in a few widths and a few formats, so the browser can pick the best format it supports at the size it needs.

Keeping a post and its photos together

The first change is structural. A post used to be a single markdown file, and anything it pointed to lived somewhere else. Now a post can be a folder that holds the content and its resources together: the markdown as index.md, with the photos beside it. The folder takes the place of the filename (date, then slug):

content/recipes/2026-10-10-ssamjang-wings/
  index.md
  trail.jpg
  seasoned.jpg
  ...

In the markdown, a photo is referred to by its filename. A line right under it, with no blank line between, becomes its caption:

![Seasoned wings on a wire rack](seasoned.jpg)
Salted, peppered, and drying under a fan while the oven preheats.

Resizing

Every photo a page uses is resized to 640, 960, and 1280px wide. The text column is 640px, so those cover 1x and 2x screens, and phones at 3x, which are narrower than the column. I had a 1920px size at first, for 3x screens at desktop width, but it came to as much as the other three together, for screens that are rare. Widths wider than the photo are skipped, so nothing gets upscaled.

Phone cameras don’t rotate the pixels when you hold the phone sideways. They store the rotation in the photo’s EXIF data and leave it to whatever displays it. The resized copies don’t carry EXIF, so the rotation gets applied before resizing.

Transcoding

Each width is encoded three times: AVIF, WebP, and a JPEG to fall back on. They go in a <picture>, and the browser takes the first format it supports:

<picture>
  <source type="image/avif" srcset="seasoned.640w.avif 640w, …" sizes="…">
  <source type="image/webp" srcset="seasoned.640w.webp 640w, …" sizes="…">
  <img src="seasoned.1280w.jpg" srcset="seasoned.640w.jpg 640w, …" sizes="…"
       width="1280" height="960" loading="lazy" alt="…">
</picture>

Go’s standard library can’t write WebP or AVIF. gen2brain/avif and gen2brain/webp wrap libavif and libwebp compiled to WebAssembly, so the build still needs no C toolchain, locally or on Netlify.

Quality numbers don’t compare

I started with AVIF at 60 and WebP at 70. On my first test photo, a smooth landscape, AVIF came out bigger. Since browsers pick AVIF first, most visitors would have been getting the larger file.

On a busier photo it goes the other way. A quality number only means something within one encoder, so how two formats compare depends on the photo. AVIF at 50 came out smallest on both, so that’s where it landed.

Here’s the trail photo from the wings post at 1280px, the size most screens get, with the same 256 by 160 crop from each at full size:

Format	Quality	Size
original		9.4 MB, before resizing
JPEG	80	888 KB
WebP	70	710 KB
AVIF	60	554 KB
AVIF	50	394 KB

The crops are saved losslessly, so each one shows exactly what its format did. WebP smooths out the speckle on the rock and lifts the dark shadows, so the rock goes a little gray. AVIF at 50 smooths the speckle a bit and softens the leaves at the top. JPEG at 80 and AVIF at 60 stay closest to the original.

Build Artifact Caching

Encoding is slow, AVIF most of all. The wings post has eight photos, and encoding them the first time takes about 40 seconds. Every copy goes into .cache/images/, in a folder named by a hash of the photo and the encoding settings. A rebuild only encodes what changed, and changing a quality setting starts over on its own.

That cache lives on my machine, though. Netlify starts every deploy from a clean checkout, so each one would encode every photo again. Netlify build plugins can keep a folder between deploys, and that only takes a small local plugin, in netlify/plugins/photo-cache:

const dir = ".cache/images";

module.exports = {
  async onPreBuild({ utils }) {
    await utils.cache.restore(dir);
  },
  async onPostBuild({ utils }) {
    await utils.cache.save(dir);
  },
};

It restores the cache before the build and saves it after, so a deploy only encodes photos that are new or changed. Since the whole folder is restored and saved every time, it shouldn’t grow forever: the build marks each entry it uses, and prunes any it hasn’t used in 30 days.

Leaving location out

Photos can record where they were taken, so anything taken in my kitchen could record where I live. Only the encoded copies are published, never the originals, and re-encoding drops EXIF along with that location.

That covers the site, but not the repo. A folder post keeps its photos in content/, and the repo is public. So photos don’t get copied in by hand. A mage task brings them in:

go tool mage photos content/recipes/2026-10-10-ssamjang-wings ~/Desktop/wings

It takes a photo or a folder of them, and writes each one into the post rotated upright, scaled to at most 2560px, and with no metadata at all. That also keeps the repo from filling up with 10 MB originals. It won’t overwrite a photo that’s already there unless it’s run with -replace.

Dropping all the metadata drops the color profile too, and iPhone photos are in Display P3, a wider color space than sRGB. Without the profile, browsers read P3 colors as sRGB and show them muted, so the task converts them to sRGB first. The build does the same for any photo that didn’t come through it.

Lazy loading

Most photos are further down the page than anyone has scrolled yet, so they load lazily. That also unlocks sizes="auto".

sizes tells the browser how wide an image will be drawn, so it can pick from the srcset before layout has happened. Normally you write that out by hand, and it’s easy to get wrong. With auto, the browser waits for layout and uses the real width. It can only do that for a lazy image, since it has to wait for layout anyway.

auto isn’t Baseline yet, so it can’t be the whole value. It goes first, and the hand-written sizes follow as a fallback. A browser that supports auto uses it and ignores the rest. One that doesn’t skips it and reads the list after it:

sizes="auto, (max-width: 42rem) 100vw, 40rem"

The catch is a photo at the top of the page. It’s on screen straight away, and making it wait is just slower. My first take was to load the first photo on each page eagerly, automatically. That works until a post opens with a few paragraphs and the first photo is far down.

So it’s declarative now. Photos are lazy unless marked, with an attribute block right after the image:

![A friend walking a rocky trail](trail.jpg){loading=eager}
Out on the trail.

goldmark’s attribute syntax only covers headings, so this is another small extension. It reads the block, removes it from the text, and gives that photo sizes without auto. Anything else in braces fails the build, so {loading=eagre} doesn’t quietly do nothing.

What’s next

Covers for the journal. /journal/ is the same list of dates and titles as the blog. A photo per trip would suit it better, I’ll tackle that when I get to actually writing an entry there.

A build step and styling adjustments

Wed, 14 Oct 2026 00:00:00 +0000

The production readiness pass ended with a list of things left to do, and one of them was a real build step for CSS and JavaScript. That’s where today started. Once that was in, I finally got to the part I’d been putting off: the styles.

A build step with esbuild

Up to now, assets went through a small pipeline of my own: hash each file, add an integrity attribute, minify the CSS and JS. That covered cache busting, but Mermaid still loaded from jsDelivr and MicroLighter was a vendored copy checked into static/.

esbuild has a Go API, which made it an easy fit. The generator calls it directly, so there’s no Node tool in the loop — npm only installs the dependencies. Every stylesheet in assets/css and every script in assets/js is an entry point:

Mermaid and MicroLighter come from npm. Both are code-split and content-hashed, so a page only fetches the chunks it uses. Each MicroLighter grammar is its own chunk.
Fonts go through esbuild too. It hashes each font the CSS references and rewrites the url(), so the preload tags and the stylesheet always point at the same file.
The old minifier is gone. esbuild minifies, so tdewolff/minify didn’t need to stay.

mage serve gets a dev mode. It keeps an esbuild context between rebuilds, so only what changed gets rebuilt, and it writes unminified files with source maps and stable names. Breakpoints in devtools survive a rebuild that way, and the dev server sends no-store so the browser doesn’t hang on to a stale copy.

Finishing off the skeleton

The site started as an AI-generated Hugo skeleton, and I swapped Hugo for my own generator a while ago. What I hadn’t noticed is that the Hugo templates never left. layouts/ and hugo.toml were still sitting there, and the generator reads from templates/.

I found out the honest way: I edited layouts/single.html, and nothing changed. Two folders of templates that look nearly the same is an easy trap, so out they went.

Styling adjustments

With the build sorted, I spent the rest of the day on the styles. Most of it is groundwork, not anything you’d notice at a glance.

This is one of the downsides of starting from a vibe-coded base. The styles work, but they aren’t organized the way I’d have organized them writing from scratch: one-off values, rules fighting each other, no system tying it together. What follows is a start at restructuring, not the finished version. I’ll keep tightening it up over time.

Splitting up the stylesheet

main.css was one long file with comment banners between sections. It’s now a list of imports, with each section in its own file under base/, layout/, pages/, and themes/. esbuild bundles them back into one stylesheet, so the split costs nothing at runtime.

The palette got the same treatment. Each color is a named variable now (--palette-moss, --palette-bark, --palette-forest-floor), and the variables the rest of the CSS actually uses (--accent, --bg, --rule) pick a light and dark value from those with light-dark(). Components only reach for the semantic names.

A font-family variable

The site switches between two families, Fira Sans and Fira Code, in a lot of places. Instead of setting font-family in each one, every element now reads its family from a variable:

:root { --font-family: var(--sans); }
* { font-family: var(--font-family); }

code, pre, kbd { --font-family: var(--mono); }

The variable inherits, so setting it on an element switches everything inside it too. The header, footer, dates, and table headers all switch to mono with one line each.

Fewer font files, then variable ones

The site was loading eight static font files. Trimming that down to the weights actually in use got me thinking about variable fonts instead.

Fira Code has a variable version on Fontsource. Fira Sans doesn’t, but Firava is a variable build of it. Its character set is much smaller than Fira Sans: about 450 characters instead of 1,700. Everything I write is in English, and checking every post turned up nothing it was missing.

Cut down to the latin range and the weights I use (300 to 500), the upright file is 37.6 KB, which is less than the two static weights it replaces. Italic was closer. Static italic files would have been a bit smaller on most pages, but one variable italic file means italic headings don’t pull in a new font when you move between pages. I’ll take consistency over 14 KB.

That’s three font files instead of eight. A small script rebuilds them, since the cut-down Firava is a file I made, not one I downloaded.

A type scale

Font sizes had drifted into a scatter of one-off values: 0.85rem, 0.9em, 0.95rem, 1.1rem, 1.15rem. They all come from a scale now. The base is 18px, each step up multiplies by 1.25, and one step down covers the small text (dates, meta, footnotes, the nav).

Line heights come from the same scale. Body text is 1.25 squared, 1.5625, and headings are 1.25.

The one deliberate exception is monospace. Fira Code runs larger than Fira Sans at the same size, so code sits a little under whatever it’s set in, not on a step of the scale.

GitHub-style alerts

I wanted callouts, and the markdown already exists for them:

> [!NOTE]
> Worth knowing.

goldmark doesn’t render these, so I wrote a small extension for it. After parsing, it looks for blockquotes whose first line is just the marker, and swaps them for an alert with a title. Like GitHub, it only knows the five types, and a marker that isn’t on its own line stays a normal quote.

Tip

This is one. They come in note, tip, important, warning, and caution, each with its own color from the palette.

Smaller fixes

Mermaid diagrams are flat. Mermaid’s newer default look adds drop shadows and gradients. The classic look with plain borders fits the rest of the site better.
The footer sits at the bottom. Short pages used to end with the footer partway up the window. A flex column on the body fixes that, without a fixed minimum height on main.

What’s next

The build step comes off the list from last time. The rest is still there: an accessibility pass, a sitemap and robots.txt, and git hooks. Styles-wise, the groundwork is in place, so the next round can be about how things look instead of how they’re put together.

A quick production readiness pass

Tue, 13 Oct 2026 00:00:00 +0000

The blog works. It builds, it deploys, and you’re reading it. Before I sink more time into the tooling or the styles, though, I want to step back and check that the basics are in place for something running in production — even something as small as this.

Production readiness review is a real thing with a real checklist. This is the lightweight version: write down what “ready” means for this site, check each piece, and fix what’s missing.

What I knew going in, and what I didn’t

Some of this was decided before I wrote a line of code. Netlify was always going to be the build and hosting target. It’s what I’ve been reaching for with static sites for personal projects, and the skeleton came with a netlify.toml already in place.

Other parts I only figured out while making the list. The big one: I want Cloudflare in front of the site for networking. I’ve spent a lot of time with Akamai, and I’d like to learn another common edge CDN while the stakes are this low.

The network, at a high level

Here’s how a request gets to a page, and how a page gets built:

flowchart LR
  reader([Reader]) -->|wrkstdy.com| cf[Cloudflare<br/>DNS + edge]
  cf --> netlify[Netlify<br/>hosting]
  dev([Me]) -->|git push| github[GitHub]
  github -->|webhook| build[Netlify build<br/>go tool mage build -production]
  build -->|public/| netlify

Two halves, really. On the read side, Cloudflare owns DNS for the domain and sits at the edge, and Netlify serves the files. On the write side, a push to GitHub kicks off a Netlify build, which runs the same Mage task I run locally and publishes public/.

Networking with Cloudflare

Cloudflare is where most of the new-to-me learning happens. The pieces I needed to cover:

DNS. Moving the domain’s nameservers to Cloudflare and pointing the apex at Netlify.
Caching. Deciding what the edge caches and for how long, and how that lines up with the headers Netlify already sends.

DNS was the easy part: the nameservers moved to Cloudflare, and the apex points at Netlify.

Caching was the interesting question. Netlify is a CDN too, so putting Cloudflare in front of it means two layers of caching to reason about. I could have spent a while working out how much each one should do, but I’m here to learn Cloudflare, not to tune two CDNs against each other. I also plan to proxy other projects on paths under wrkstdy.com, and that routing belongs at the edge anyway. So Cloudflare does the edge caching, and Netlify serves the files.

I started with simple defaults. Cloudflare caches HTML at the edge for a day and the hashed assets for a year. Anything with a status of 300 or above gets a much shorter TTL, so a redirect or a 404 doesn’t stick around at the edge after I fix it.

Behind the edge, Netlify’s headers tell browsers how long to keep things. Everything under /assets/ (fonts, CSS, JS, icons) has a hashed name and a year-long immutable cache header. Their names change whenever their contents do, so there’s nothing to invalidate.

HTML is different. Netlify sends max-age=0 for pages by default, which I’ve loosened to an hour. That means a deploy can take up to an hour to reach someone who already has a page open, which is a fine trade for a blog. A day at the edge is the part I don’t want to wait on, so a Netlify build plugin, netlify-purge-cloudflare-on-deploy, purges Cloudflare’s cache after every production deploy. A new post shows up at the edge right away, not a day later. It’s set up in netlify.toml to run for production only, so pushing to a pull request doesn’t empty the cache for the live site.

Builds in Netlify

The build side is in better shape. netlify.toml pins the Go version and runs go tool mage build -production, which runs go vet and the tests first and fails the deploy if either fails. Deploy previews and branch deploys get the same build with their own base URL, so links work on preview URLs too.

The HTML itself

Next is the output: is the markup semantic, and is anything missing?

A quick look turned up a few gaps right away:

No favicon. Every browser tab showed the default icon, and every page load logged a 404 for /favicon.ico.
No robots.txt or sitemap. Hugo generated these for free. My generator doesn’t, yet.
No 404 page.

The favicon is the wordmark’s ~/ in Fira Code SemiBold, outlined into an SVG that follows light and dark mode. Next to it there’s an apple-touch-icon and a root favicon.ico for clients that still ask for one there.

The 404 page is a markdown file, content/404.md, that the generator writes to /404.html, which is where Netlify looks for a not-found page. It gets a noindex tag instead of a canonical URL, and a test makes sure it stays that way.

The structure itself is in decent shape: a lang attribute, a single <main>, a labeled <nav>, a canonical URL, and a description on every page. I still want to run each page through a validator and an accessibility checker instead of trusting a quick read.

Assets, and what else loads

Assets already go through a small pipeline. Each file in assets/ is written under a content-hashed name, with a Subresource Integrity hash for the integrity attribute. That covers cache busting.

It didn’t minify anything, though. With one stylesheet and one small script, I didn’t expect it to matter much, so I measured first. Gzipped, the stylesheet is 2.4 KB and my script is 0.7 KB. Minifying takes those to 2.2 KB and 0.6 KB. That’s a few hundred bytes, small but free, so the pipeline now runs CSS and JS through tdewolff/minify before hashing them. Minifying comes first so the hash and the integrity attribute match the bytes that are actually served.

The real weight is somewhere else. Diagrams like the one above load Mermaid from jsDelivr: about 208 KB gzipped, spread over 25-plus files. That’s more than everything else on the page combined, and it comes from someone else’s server. For now, Mermaid only loads on pages with a diagram.

Concatenating and serving Mermaid myself both point to the same thing: a proper build step for CSS and JavaScript. That’s a bigger change than this pass, so I’m deferring concatenation until I add one, and I’ll work out how to deliver Mermaid at the same time.

I also checked what loads that I didn’t put there. Cloudflare turns on its Real User Monitoring by default, which adds a beacon script to every page. I may want those numbers later, but for now it’s off.

A first pass at CI

Until this pass, the only automated check was the one Netlify runs on deploy. That meant a broken test showed up as a failed deploy, not before it.

The first step was a GitHub Actions workflow on pull requests and pushes to main. It runs go tool mage test and a build with drafts, on the same Go version Netlify pins, so a failure shows up on the PR instead. Drafts are in that build on purpose: deploy previews include drafts too, so a post can be reviewed on its PR before it’s published.

Branch protections on main back that up. Every change goes through a pull request, and both the CI job and Netlify’s deploy preview build have to pass before it can merge. It’s just me, so there are no required approvals.

Things left to do

I’m leaving a few things for another day:

Accessibility. Run every page through a validator and an accessibility checker, and fix what they find.
A sitemap and robots.txt. Hugo generated these for free. My generator doesn’t, yet.
Git hooks. Run the same Mage checks before a commit or push, not just on the PR.
A build step for CSS and JS. Concatenate assets, and serve Mermaid myself instead of from jsDelivr.

None of it is exciting, but all of it is the kind of thing that’s easy to skip on a side project and annoying to find out about later. With the basics in place, I can get back to the parts I actually want to spend time on: the tooling and the styles.

Building a blog the long way, on purpose

Mon, 12 Oct 2026 00:00:00 +0000

I’m writing a blog.

Narrator: you may be wondering how I found myself here.

After 14+ years at Mailchimp, I have something I haven’t had in a long while — time to poke at things just to see how they work. I want somewhere to keep track of that, so here we are: a blog.

A blog generator is a pretty solved problem though. I could have grabbed Hugo or 11ty, dropped in a theme, and been writing this post in an afternoon. Which is exactly why I’m not doing that. (spoiler: Based on how I started it, this still took just an afternoon. Maybe just a longer one)

Overengineering on purpose

I’m treating this site as a practice field. I already know what a blog needs to do — turn some markdown into HTML, list some posts, look decent in light and dark — so I don’t have to figure out what to build. That leaves all my attention for how, and the how is where I want to learn.

Go has been on my radar for a long time. I’ve dabbled, but never really had the hands-on time to learn it properly. I like how small the language is and how that nudges everyone toward the same style — one formatter, one loop keyword, not a lot of ways to be clever with the language itself.

So the site is built by a small generator I’m writing myself: goldmark for markdown, the standard library’s html/template, fsnotify watching files for the dev server, and Mage to run tasks. None of it is necessary. That’s kind of the point.

Building a blogging engine isn’t really new for me. I have deep experience with static site generators via Middleman, and I’ve tried this exact trick before. Digging through my old site, I found a draft from 2014 for “Middlewareman” (yes, the name was a pun), a static site generator I was going to write in Clojure to learn a bit more of the language. And now twelve years later — same idea, different language.

Starting from a vibe-coded skeleton

I’ll be upfront: the first real commit of this site wasn’t mine, not really. I described what I wanted (a forest color scheme was obviously a must) and had AI generate a Hugo skeleton — layouts, syntax highlighting, the works. I didn’t want the lack of a build system standing between me and getting started.

Since then, I’ve made a few “critical” edits to get closer to what I had in mind:

Swapped Hugo for my own Go generator. Hugo does its job well, maybe too well. It’s hard to learn Go from a tool that does everything for you.
Cut tags, the separate post archive, and RSS. The skeleton came with all the things a “real” blog has. With one post, the home page list is archive enough, and I don’t have anything to tag yet, so out they went. They can come back when they earn it.
Added Mage. I know Rake well, so I went looking for something similar in Go, and Mage’s Rake-style commands were a great fit. Now it’s go tool mage serve instead of remembering a handful of go run incantations, and Netlify runs the same check task I do.

These changes move it more towards what I want than the starting point. I expect that to keep going, and I’ll write about it as it does.

Working with AI, differently

At Mailchimp I had a solid AI toolset, but it was about doing work — getting a known task done faster. Here I want to explore the ways of working themselves: what’s worth handing off, what I want to keep my hands on, and where the back-and-forth actually makes the result better.

Up to now I’ve been heavily invested in a plan → implement → review workflow: agree on the approach first, build it, then look the result over. It works, and I want to see what else is out there. Next I’d like to try playbooks and loops, where the steps are written down once and run repeatedly, instead of me walking each task through the same stages by hand.

This post is a small example of where things stand. I outlined my points and notes, then had AI help fill them in with prose, and steered it from there. The voice isn’t fully mine yet — putting together a solid voice and tone guide is on my to-do list.

What’s next

First, more adjustments to the blog itself, including a pass to check it’s ready for production. Beyond that, I have a few projects in mind that I’ll share here once they’re started, along with how I worked through them — dead ends included. Two I’m eyeing: a fishing notes app that ties your notes to a location and its watershed, and a CSS themer for raw markdown. No promises on either yet.