cratly

Appearance

ADR 0011 — What describes a picture is kept beside it ​

  • Status: Accepted
  • Date: 2026-11-14
  • Context repos: cratly.io site (this repo), scavold, editor

Problem ​

Sections crop pictures: a cover fills the screen, a grid gives every photo the same shape, a page list shows each page's lead image as a teaser of one format. Cropped around the middle, a portrait loses its face and a group photo its people at the edge. Where a picture keeps its subject when cropped is a property of the picture, not of the place it is used. Kept with each use, it would have to be repeated wherever the picture appears again — and a page list teaser has no place at all for it, as the author never inserted that picture there.

More of the same kind will follow: credits, a default alternative text. None of it belongs to a page.

Decision ​

  1. One sidecar file per media file. What describes media/team/anna.jpg is kept in media/team/anna.jpg.yaml: the full file name plus .yaml, in the same folder. The first key it knows is focus, the point to keep in view, as percentages of width and height. See the reference.

  2. Neutral values. focus: [30, 60] is a point in the picture, not a CSS value. How an adapter keeps it in view is its business.

  3. The sidecar follows its file. Deleting a media file deletes its sidecar; replacing a file's content drops it, since it described the picture that is gone. A tool that moves or renames media moves the sidecar along.

  4. A use may still override. A section argument naming a focal point for one use wins over the sidecar. The sidecar is the default, not a lock.

Considered and rejected ​

  • One file per folder or per site, listing every picture. Fewer files, but every change of any picture's focus edits the same file, so two drafts touching different pictures conflict on publishing.
  • Metadata inside the picture (XMP, EXIF). It travels with the file even outside cratly, but every change rewrites the binary, which bloats the repository's history, and writing it from a browser for every format is a project of its own.
  • Per use only, as section arguments. That is what this decision corrects.

Consequences ​

  • The media folder holds files that are not media. Editors leave sidecars out of their media listings, and adapters do not publish them.
  • A picture without a sidecar behaves as before: cropped around its middle.
  • New keys extend the sidecar without a new file format. Tools ignore keys they do not know, as they do in .cratly.config.yaml.