Writing

Pictures

Put pictures in static/, describe them for people who can't see them, and keep them light. The editor does the resizing for you.

Add a picture to a page

  1. Put the picture in static/. A good habit is a folder per month: static/media/2026/10/new-oven.jpg. Anything in static/ is published at the same place, without static: this one is at /media/2026/10/new-oven.jpg.

  2. Put it in the page with Markdown, where you want it to appear:

    ![A loaf of bread fresh from the new oven](/media/2026/10/new-oven.jpg)

  3. Add a caption if you like, as a line in italics just under it:

    *Fresh bread every two hours, from 7am.*

An article with a picture of a loaf of bread under its first paragraph

Describe every picture

The words in the square brackets are the picture's alt text: what screen readers read aloud, and what shows if the picture can't load. Say what the picture shows, in a sentence: "A loaf of bread fresh from the new oven", not "image1" or "bread.jpg".

A picture that's only decoration can have empty alt text, ![](/media/swirl.png), so screen readers skip it. The checks warn about pictures with no alt text at all.

When someone shares a page on Mastodon, LinkedIn or in a chat app, the preview shows a picture. Set it in the front matter:

image: /media/2026/10/new-oven.jpg
image_alt: A loaf of bread fresh from the new oven

Pages without their own picture get a generated card with the page's title, in your site's colors, as long as cards: true is in site.yaml (the template has it on).

Keep pictures light

Big pictures make pages slow, especially on phones. Aim for:

  • No wider than about 1600 pixels. That's plenty for any screen.
  • Under 500 KB each. The checks warn about anything heavier.
  • JPEG or WebP for photos, PNG for drawings and screenshots with flat colors.

Uploading through the editor does this for you. It resizes every picture, makes smaller copies for phones and a WebP copy, and removes hidden details such as the camera and the GPS location. See Pictures in the editor.

Location data

Phones store where a photo was taken inside the file. On a personal site, that's often your home. The checks refuse to publish a JPEG that still has its location (image-location). To fix it, upload the picture through the editor, or remove the location with your photo app before adding it (most have an option to share without location).