Putting images in a post

September 9, 20263 min read

Every image on this blog goes through one component. This post is what that looks like, and doubles as the fixture the layout tests render against.

The default

An image written as ordinary markdown renders at the width of the prose, as a real <figure> with its title as the caption:

The captain's chair at a Star Trek convention — Markdown image syntax, rendered at the prose measure.

The #1080x945 on the end is not decoration. It is the image's intrinsic size, and it is what lets the browser reserve the right box before a single byte of the image has arrived. Without it the text below jumps down the moment the image loads — the layout shift that makes a page feel broken to read on a slow connection. Markdown has nowhere else to put that number, so it goes in the URL fragment, which is the one part of a URL that never reaches a server.

An image written without it still renders. It just does not get a figure, a caption, or a reserved box.

Breaking out

Some images want more room than the text does. wide breaks out past the measure on a screen wide enough to hold it, and falls back to the ordinary width on anything narrower:

An abstract long-exposure photograph taken at the convention — The wide layout, which breaks out past the text measure on a large screen.

Floating beside the text

left and right float, so the prose wraps alongside. Below 48rem there is no room for two columns and the image stacks back to full width instead — a float on a phone produces three words a line, which is worse than no float at all.

The captain's chair, shown at half the text width — Floated right.

The paragraph you are reading is what wraps beside it. The float is cleared before the next heading, so a section never begins in the narrow column left over beside the previous section's image — which would read as a second caption rather than as a new section.

Prose long enough to run past a floated figure also shows the other half of the arrangement. A float is out of the normal flow, so the article itself has to be told to contain it, or the image hangs past the end of the post and overlaps whatever comes after.

Two at a time

gallery puts several images in a grid under one shared caption, which is the right shape when they are meant to be compared rather than read in sequence:

The captain's chair, as photographed directly — A gallery: one figure, one caption, two images.

The same evening, as a long exposure — A gallery: one figure, one caption, two images.

It stays one <figure> with one <figcaption>. Nesting a figure per image would give each its own caption slot for a caption that describes the set.

What the browser is told

Every layout supplies a sizes string describing how wide the image will actually be, and a srcset of renditions to choose from. That pairing is what lets a phone download a 640px image where a desktop gets a 2048px one, and it has to be declared rather than measured: the browser picks a candidate from the preload scanner, long before any stylesheet has been applied and there is anything on the page to measure.

Every candidate is cropped to the same aspect ratio as the image it replaces, so choosing a different one can never change the shape of the box that was already reserved.