Image guidelines for the blog
Where uploads are stored, which sizes to use, and how the build turns one file into a responsive set of images.
Images are the heaviest part of most posts. This site optimizes them at build time, but the build can only work with what the writer uploads. These rules keep pages fast.
Where files go
Every upload goes to src/assets/uploads/. The browser editor does this for
you. Frontmatter then stores the repository path of the file, for example
/src/assets/uploads/cover-example.jpg.
Files in that directory are processed by the build. Files in public/ are
copied without any processing, so use public/ only for items that must keep a
fixed name, such as the favicon.
Which size to upload
| Use | Size | Format |
|---|---|---|
| Cover image | 1600 x 900 | JPEG or WebP |
| In-post figure | 1200 wide | JPEG, WebP, or PNG |
| Author portrait | 512 x 512 | JPEG or WebP |
Upload the largest version you have, up to about 2000 pixels wide. The build creates the smaller sizes. It never creates a larger one, so a small upload stays small on a wide screen.
What the build does
For each image the build produces several widths in a modern format, writes the
correct srcset and sizes attributes, and sets the intrinsic width and
height. The height and width stop the page from jumping while the image loads.
Always write alt text
The schema refuses a cover image without a coverAlt value. Describe what the
image shows, not what it is. “Team reviewing a deployment dashboard” helps a
reader. “Photo” does not.
If an image is decorative and adds no information, say so in the review and use a short, factual description anyway. A cover image is never truly decorative, because it appears alone in social previews.
Keep the subject in the middle
Cards crop cover images to a 16 by 9 box, and social previews crop them to a 1200 by 630 box. A subject near the edge can disappear. Keep the important part of the picture close to the centre.