The editor

Images

Images live in the page's own folder, so they move with the page. The build reads their sizes and makes smaller copies of wide ones for phones.

Image fields

A template places an image field in an attribute, usually an image's src:

<img src="{{ cover:image }}" class="w:full h:auto">

In the editor, click the image to open its panel. From there you can:

  • Choose or replace the image from a file on your computer.
  • Write its alt text, a short description for people who can't see it.
  • Remove it from the field.

Faster still, drag an image file from your desktop and drop it onto the image. It's replaced as soon as it's uploaded, and its alt text is kept.

An empty image field shows a grey placeholder in the editor, so there's something to click. On the published site an empty field has no address at all, so wrap optional images in a condition:

{{ if:cover }}
  <img src="{{ cover:image }}" class="w:full h:auto">
{{ /if }}

An image field used somewhere you can't click, like a social sharing image in the page's head, appears in Page settings instead.

Images in rich text

In a rich field that allows images, drop an image file where you want it, paste one from the clipboard, or use the image button in the toolbar. Each becomes a figure with a caption you can type under it. Click the image to select it; the toolbar then shows a box for its alt text and a button to remove it. Typing or pasting while an image is selected starts a new line after it, so you can't replace a picture by accident.

What Verso accepts

JPEG, PNG, GIF, WebP and AVIF, up to 25 MB each. Verso checks what a file really is from its contents, not its name, so a renamed file can't slip through.

Where images are kept

An uploaded image is copied into the page's folder, next to its page.json. Its file name comes from the original, made safe for an address: Studio Table (final).JPG becomes studio-table-final.jpg. If the page already has a different image by that name, Verso adds a number. If you upload the same image twice, it reuses the file it already has.

content/journal/the-first-week/
  page.json
  body.html
  cover.jpg
  wall-of-cards.jpg

In page.json, an image field is stored as its file name and alt text:

"cover": { "file": "cover.jpg", "alt": "Index cards pinned to a wall" }

Because images belong to their page, moving the page in the site view takes them along, and nothing ever points into another page's folder.

Sizes, and smaller copies

Verso reads each image's width and height and writes them on the <img>, unless your template already set a width. The browser can then hold the right space before the image loads, so the page doesn't jump. Images in rich text also get loading="lazy".

When you build, wide images get smaller copies. Any JPEG or PNG more than 800 pixels wide is resized to 640, 1024 and 1600 pixels (never wider than the original), and every <img> showing it gets a srcset and sizes, so a phone downloads a fraction of the bytes. This includes other pages that show the image, like a journal listing its posts' covers.

<img src="/journal/the-first-week/cover.jpg" width="2400" height="1600"
  srcset="/journal/the-first-week/cover-640.jpg 640w, … , /journal/the-first-week/cover.jpg 2400w"
  sizes="(min-width: 64rem) 64rem, 100vw">

GIF, WebP and AVIF files are used as they are. The copies are made in pure JavaScript, so they work on any host, and they're kept in .verso-cache/, keyed by each image's contents. The first build of an image-heavy site takes a while; after that, only new or changed images are resized.