Media, and the social card

One store, addressed by content

Every image in the publication — article covers, illustrations, book covers, deck slides, the figures in this book — lives in one media store and is served as a plain file.

Files are named by a hash of their own bytes. Upload the same picture twice and it is stored once; upload a changed version and it becomes a different file with a different name. Nothing is ever silently overwritten, and nothing accumulates duplicates.

The other half of storing an image is measuring it. Dimensions are read out of the file itself rather than taken on trust from whatever uploaded it. That matters in two places: pages can reserve the right amount of space before an image has loaded, so nothing jumps as it arrives; and social cards can honestly declare their own size, which is the subject of the rest of this chapter.

The card problem

When a link is pasted into a professional network, a crawler fetches the page, reads a handful of metadata tags, and renders a preview card.

Get it right and the link renders large, with the image, the headline and the description. Get it wrong and it renders as a small square thumbnail beside two lines of text — or as nothing at all.

The failure mode is what makes this worth a module. The crawler does not tell you. There is no error. The card is simply worse, and you find out by posting a link and looking at it, which is exactly the wrong moment.

The rules, in one place

The requirements are specific: a recommended size of 1200×627, a minimum width below which the large card degrades, an aspect ratio that cards get cropped to, a maximum file size, and a short list of formats that actually get rasterised.

That last one has a trap in it. Vector images are not rendered by these crawlers. A crisp, scalable, perfectly good logo produces a blank card.

These rules live in exactly one place in the system and are applied in three: the editor checks an image the moment it is uploaded, a pre-publish check verifies every published book and deck still has a valid card, and the tests assert the rules themselves.

What that looks like while writing

Uploading a social image gets an immediate verdict. Errors mean the card will be wrong or missing. Warnings mean it will render but not as intended — worth saying, never worth blocking a publish over.

The details panel then shows the card as it will actually appear, cropped to the ratio the network will crop it to. Which is the point: a portrait cover looks lovely in a book listing and loses its title and its author when cropped to a wide card. Seeing that before publishing is the whole feature.

Books and decks each carry a separate wide image for this reason. A book’s cover is portrait because that is what a book looks like on a shelf; its social card is a different image, purpose-built at the right shape. The two are not the same picture at different sizes, and pretending they could be is how covers get beheaded.

Alt text

Every image field that can carry alt text does, and the deck module treats it as close to mandatory in spirit — a deck is nothing but images, so alt text is the only thing standing between the content and a reader using a screen reader.

For decorative images — a cover behind a title, a stacked thumbnail on a card — the alt text is deliberately empty, which is the correct way to tell assistive technology that an image carries no information a caption has not already given.