Style
This is my /style page: the editorial standards I write to. For a visual reference of the HTML elements and styles on the site, see the styleguide.
Quotes vs Italics
Rules of thumb for when to use quotation marks, italics, or neither:
- Quotation marks for direct speech or verbatim text from a source.
- Italics for emphasis, titles of long works (books, films, albums, TV series), words-as-words, and framing a rhetorical question or phrase as an object of discussion.
- Neither when a colon plus plain prose reads cleaner.
Examples of the same rhetorical framing three ways:
The question being asked is: should Democrats be allowed to redraw districts now that they're in power in Virginia?
The question being asked is: should Democrats be allowed to redraw districts now that they're in power in Virginia?
She said, "I'm not voting for either of them."
A question takes a ? even when framed by italics or a colon.
Emphasis and Scare Quotes
Italics and bold are not two strengths of the same thing. They mean different things, and HTML already draws the line:
- Italics (
<em>) are stress emphasis. They change how the sentence sounds read aloud. "The web needs engine variety." - Bold (
<strong>) is importance or seriousness. It doesn't change pronunciation, it says this part matters more. "Not just no but fuck no." Use it rarely; italics is the default.
Italics is also the mark for the things I'm mentioning rather than saying: words-as-words, titles of long works, and rhetorical framing (see above).
Scare quotes take quotation marks, not italics. When I'm distancing myself from a term rather than mentioning it, air quotes around something I don't think deserves the name, that's quotation marks. This follows Chicago 7.57 and MLA.
I don't want "AI features" baked into everything.
One of the worst offenders at giving its users unwanted "features".
The line: italics for a word I'm pointing at, quotes for a word I'm handing back to whoever said it. A phrase I actually identify with is not a scare quote, so it stays in italics ("I'm in the LLMs are a tool camp").
Quotation marks are double. Single quotes only nest inside doubles. Typing air quotes as single quotes is a habit worth catching on every edit pass.
Quotes with a Citation
When quoting a written source (an article, book, or web page), follow the quote with a <cite> attribution line: the author and the work's title, with the title linked to the source. The site styles the <cite> for you, on its own line below the quote in muted monospace with a leading em dash, so don't type the dash yourself. In markdown blog posts, use this format:
> The passage you're quoting goes here.
>
> <cite>Author Name, [Source Title](https://example.com/article)</cite>Which renders as:
The passage you're quoting goes here.
Author Name, Source Title
For a spec-pure citation in a hand-written HTML post, place the attribution outside the blockquote in a <figure> / <figcaption>, and put the source URL in a machine-readable cite attribute on the <blockquote>:
<figure>
<blockquote cite="https://example.com/article">
<p>The passage you're quoting goes here.</p>
</blockquote>
<figcaption>— Author Name, <cite><a href="https://example.com/article">Source Title</a></cite></figcaption>
</figure>Which renders as:
The passage you're quoting goes here.
Use this only when you're hand-writing HTML; the markdown form above is the default for normal posts.
Fediverse / Mastodon Quotes
When quoting a Mastodon or fediverse post, use a blockquote with a <cite> attribution line (same treatment as the citations above) that includes display name, handle, and post date. The post content is preserved in our source files even if the original is deleted. In markdown blog posts, use this format:
> The text of the post you're quoting.
>
> <cite>Display Name ([@user@instance.social](https://instance.social/@user/123456789)) · Nov 20, 2025</cite>If the post has no display name (or it's the same as the handle), drop the display-name parens:
> The text of the post you're quoting.
>
> <cite>[@user@instance.social](https://instance.social/@user/123456789) · Nov 20, 2025</cite>Which renders as:
You don't mass-adopt the open web by mass adopting it, you mass-adopt the open web by making great stuff that makes people want to use the open web.
Ada Example (@example@mastodon.social) · Nov 20, 2025
The scripts/quote-toot.js tool generates this format automatically from a toot URL and copies it to the clipboard.
If the post may be removed, also consider archiving it and linking to the archived version as a fallback.
Update Banner
Used in blog posts to call out updates or corrections added after the original publication date. Uses an <aside> element with the update-banner class.
<aside class="update-banner" aria-label="Blog post update">
<p><strong>01/15/2026 Update:</strong> Your update text here.</p>
</aside>Journal Note
An introspective, scene-setting note for journal-style posts: where I am, what time it is, what's happening around me as I write. Uses an <aside> with the journal-note class and a small coffee mark. In a markdown draft I write it as a single !journal: directive line (one paragraph), and it expands into the markup below when I publish:
!journal: As I'm typing these words, it's 6:07am on a Sunday morning. I know it's humid out because the humidity is causing the fingerprint sensors on the door locks to beep. The cat feeders have just hit and the cats are milling about.Which renders as:
Photo Caption
To caption a photo inside a post, follow the image with a !caption: directive line. In a markdown draft I write the image and caption together, and on publish they expand into a captioned <figure>:
!caption: The caption readers see, in my own words.The ![...] text is the alt text (a description for screen readers and when the image fails to load); the !caption: line is the visible caption. Which renders as:
Photo Gallery
A run of photos that belong together goes in a gallery rather than down the page one at a time. Open with !gallery and list the images:
!gallery
!endgalleryThey render as a justified grid, the same layout my imported Flickr sets use, so an authored gallery and an imported one are indistinguishable.
The block runs from !gallery until !endgallery, the first line that isn't an image, or the end of the post. !endgallery is optional for that reason, and blank lines between images are fine because Typora inserts them whether I want them or not.
Two things behave differently inside a gallery than outside it. Captions are ignored: the justified layout has nowhere to put a <figcaption>, so a photo that needs a caption wants to be a standalone image instead. And a gallery is always expanded, never collapsed behind a toggle, because if the photos were worth taking they're worth showing.
Alt text still comes from the ![...] slot per image, or gets filled in at publish when I leave it empty.
Rating
A star rating for reviews, drawn with the same stars as my book and watch logs. In a markdown draft I write a !rating: directive line with a number from 0 to 5 (halves allowed, e.g. 4.5), and on publish it expands into the star markup below, carrying a p-rating microformat so it's machine-readable:
!rating: 4.5Which renders as:
Footnotes
Use footnotes for asides you want to keep but don't want to interrupt the main line of thought. Good uses:
- Sources and citations where an inline link would be clunky.
- Clarifications and caveats (for example: "I mean X here, not Y").
- Tangents and wry side-comments you can't let go of.
- Attribution for a phrase or idea without breaking sentence rhythm.
Don't use footnotes for content that actually belongs in the paragraph, for simple links (use an inline link), or in short posts. Keep it to roughly 3 or 4 per post under normal circumstances.
Heuristic: write the post without footnotes first. On re-read, ask "is there anything I cut that I wish I'd kept?" That's footnote material.
Markdown syntax:
This is a sentence with a footnote.[^redistricting]
[^redistricting]: The footnote content. Use a descriptive name
instead of a number; it auto-numbers in the output, and
named references are easier to keep track of while editing.Footnote definitions can go anywhere in the file, but end-of-file is conventional. Continuation lines in a multi-paragraph footnote are indented 4 spaces.
Which renders as:
This is a sentence with a footnote.[1]
The footnote content. Use a descriptive name instead of a number; it auto-numbers in the output, and named references are easier to keep track of while editing. ↩︎
Recipe Posts
Most of this page is about markup. This one is about shape: the order I put a recipe post in, so every one of them reads the same way and I don't have to re-decide it each time. Mostly these are smoker and grill cooks, but the same skeleton holds for anything I make in the kitchen.
The sections, in order:
- Title. The dish, plainly. Not a pun.
- Intro, two to four paragraphs. Why I cook this and what problem it solves. This is the part that's actually mine. It stays short on purpose: the thousand-word childhood reminiscence before the ingredients is the single most hated thing about recipe blogs, and I'm not adding to it.
- Lead photo: the finished plate. Not a prep shot. This image is what gets pulled for the tag-page thumbnail and the card when the post syndicates out, so it has to be the one that makes someone want to cook it.
- Gear. What I cooked on, plus any tool the recipe genuinely depends on. If a leave-in probe is the difference between this working and not working, say so here rather than three steps into the cook.
- Ingredients. A real list with real quantities, above the method. Never buried under the story.
- Prep. Numbered steps. Prep photos live here, with a
!caption:line under each. - The cook. Temps, times, targets. Times are estimates and internal temperature is the instruction: go by temp, not by clock.
- Doneness and what goes wrong. How I know it's right, and the specific ways it fails. This is the section most recipes skip and it's the one I'd want if I were cooking someone else's.
- What I'd change next time. Honest. A recipe I've cooked once and a recipe I've cooked ten times are different documents and the reader deserves to know which one this is.
- Cook log link, when there's a specific cook behind the recipe worth pointing at.
Tags: Recipes on every one, plus Grilling when it came off the grill or the smoker.
The skeleton I start from:
## Gear
- Equipment, and the one tool this depends on
## Ingredients
- Quantities, for real
## Prep
1. Step
!caption: What's happening here.
## The cook
Temps, times, targets. Go by temp, not clock.
## Doneness, and what goes wrong
## What I'd change next timeThe intro and the finished-plate photo go above the first heading, so the post opens with prose and an image rather than a wall of headings.
Work Posts
Like the recipe section above, this one is about shape rather than markup: how I tag the posts about my working life so they read as one body of work instead of a scattering of unrelated technical notes. Three axes, and a post carries one from each where they apply.
Umbrella
Career goes on every post in this program, the technical ones included. That's the whole point of it: the tag page should show a reader who I am professionally, not just the times I wrote about changing jobs.
The test for whether a post gets it is whether I'm present in the writing. A case study where I explain what I built and why gets Career. A bare troubleshooting note that reproduces an error message and its fix does not, because anyone could have written it.
Shape
What kind of post it is. These are deliberately few:
JobRetrospectivefor the lessons-learned posts written at the end of a job.CaseStudyfor portfolio pieces: here was the problem, here's what I built, here's how it turned out.HowTofor explainers, including the "how I like to do this" ones. An approach post is still a how-to.
Not every post needs a shape tag. An opinion piece about the state of a platform isn't any of these, and forcing it into one is worse than leaving it off.
Stack
The technology, always as a pair: the umbrella and the specific thing, so a post is reachable from both directions.
PowerPlatformoverPowerAppsandPowerAutomateSharePointoverSharePointOnlineandSharePoint2013PowerShelloverPnPPowerShell
Version and flavor tags stay. SharePoint2013 is worth keeping as its own tag because the version is the reason the post exists, but it rides alongside SharePoint rather than replacing it.
Trip Reports
A trip report is an ordinary blog post, the same way a recipe is. Rides, hikes, and road trips are one format, not three: the thing that changes between them is a couple of fields, not the shape of the writing.
The test for whether something is a trip report rather than a photo post is whether I'd want the details back if I were deciding to go again. A nice afternoon with good pictures is a photo post. A route I'd repeat, or warn someone off, is a trip report.
One line, no fields
The whole block is a single directive in the body naming the GPS track:
!bike-trip ride.gpxThere is no trip frontmatter, and that's the rule rather than an accident. Anything worth showing has to be derivable from the track, or it doesn't get shown. A field I have to remember to fill in is a field I will eventually leave empty, and a half-filled readout is worse than none.
Derived on every build: distance, moving time, average speed, and climb. Looked up once when the post publishes and then frozen beside the track: where it was, and what the weather was doing. That split is about cost, not principle. The lookups hit other people's servers, and Eleventy rebuilds constantly.
The mode lives in the directive name rather than a field, so !hiking-trip and !roadtrip can render different blocks from the same kind of file. A road trip has no meaningful moving time and nobody wants an elevation profile of I-95. Naming the track as the argument also lets one post carry two of them: two days of a tour, or the ride out and the ride back, are two lines.
Things I tried in that strip and took back out: surface, shade, battery, and a hand-written route name. The first three are sentences rather than readings, and they belong in the prose where I can say why the exposed stretch mattered. Battery was worse than useless, because swapping one mid-ride makes the number simply wrong. The route name was just a field to forget.
Shape
- Title.
Trip Report: <where>. Plain, and consistent with every one I've written since 2012. - Intro, short. Why this trip, what I was after. It comes first because a stat strip is an answer, and landing on one before anything has posed a question makes the post open like a dashboard. Two or three sentences is plenty: same discipline as the recipe intro.
- Lead photo. The one that makes someone want to go. This is what gets pulled for the card and the tag-page thumbnail, so it's the view, not the trailhead sign.
- The trip block. Stats, map and profile together, still near the top. Someone reading to decide whether to do this themselves wants how far, how hard and where, in one glance. Burying the route below the story makes them scroll to find out where I actually went.
- How it went. The narrative, and the actual post. Surface, shade and how the battery held up live here, in sentences.
- Stops. Food and detours worth knowing about, each with the date I was there. An undated hours line is worse than none, because a fifteen-mile ride to a locked door is a real cost.
- What I'd do differently. The section that keeps an old report useful. Including "nothing, I'd do it again exactly."
- Photos.
Most of that list is a mental map, not literal headings. Nineteen of my trip reports carry no h2 at all, and they're right not to: a trip report is a story, and a heading announcing that the post is about to be the post helps nobody. The exceptions are the two sections a reader jumps to rather than reads through, so those get real headings. A multi-day tour is the other exception, where each day is a heading.
The skeleton I start from:
Why this trip, in a paragraph or two.
!bike-trip ride.gpx
The story. As long as it wants to be, no headings unless
it's a multi-day trip and each day needs one.
## Stops
- Place, what I had, verified YYYY-MM-DD
## What I'd do differentlyTags
TripReport on every one, plus the mode as an umbrella-and-specific pair, the same way the work posts above do it: Cycling with eBike or CycleTouring, Hiking with the trail. The umbrella is what makes the tag page show the whole body of it rather than one bike's worth.
The track is the artifact
The GPX file lives in the post bundle and gets committed, not just the map image drawn from it. The image is a rendering and can be made again; the track can't. It's also plain XML, which means it survives into the portable archive intact, and a proprietary binary from a watch vendor would not.
Tracks get trimmed at both ends before they go in. A watch starts recording at my front door, and a published trip report should not geolocate my house.