Give linked images SEO-friendly filenames

What you'll see

You link an embedded image from template code — a card thumbnail in a listing, a logo, a portfolio shot — using Docly's image scaling URL. It renders at the right size, but look at what the image is actually served as:

<img src="#item.Url#/#item.Image1#/500x400x1/image.jpg" alt="photo-10" />

Every generated image lands under the same throwaway name — image.jpg, photo-10.jpg, or a raw attachment id — and the alt text is leftover boilerplate. The page itself ranks, but the pictures carry no descriptive signal of their own. On a site where the images could be pulling in image-search traffic, that is free SEO left on the table.

What's actually happening

Docly serves a scaled copy of an embedded image from a four-segment URL:

<page-url>/<image-field>/<width>x<height>x<mode>/<virtual-name>.jpg

Each segment has a job:

• <page-url> — the URL of the document or folder that holds the image (for example #item.Url#).
• <image-field> — the value of the field the image is stored in (for example #item.Image1#). This is the attachment Docly actually reads.
• <width>x<height>x<mode> — the scaling instruction: target width × height × a scale-mode digit (e.g. 500x400x1 is 500×400 in mode 1, "scale to fill"). See Image scaling for the mode list.
• <virtual-name>.jpg — the virtual name. This last segment is decorative. The first three segments already identify and scale the image, so Docly does not read this part to find the file — you can put anything here. But it is the filename the browser, the server logs, and search engines see.

That is the leverage point. A file's name is a recognised relevance signal for image search: a descriptive, hyphenated, keyword-bearing filename outranks a generic one for the same picture. image.jpg and photo-10.jpg throw that signal away; a name that describes the picture — ideally the subject of the page it illustrates — captures it. Because the segment is free-form, you get this for nothing: the same image bytes, served under a better name.

What to do

1. Set the virtual name to a descriptive slug. The strongest default is the page's own title, because the image illustrates that page. This is exactly what /tjenester does — each service thumbnail is named after the article it links to:

<img src="${encodeURIComponent(f.Url)}/${f.Image1}/128x128x1/${encodeURIComponent(f.Title)}.jpg"
     alt="${f.Title}" />

The thumbnails are then served as Systemutvikling.jpg, Altinn-utvikling.jpg, Databaseutvikling.jpg and so on — one descriptive filename per service.

2. Always wrap the title (and the URL) in encodeURIComponent(). Titles contain spaces and Norwegian characters (æ ø å); encodeURIComponent turns them into a clean, valid path segment. Without it, a title like Konvertere Access til SQL would break the URL at the first space.

3. A fixed keyword works too. When a whole listing should target one phrase rather than per-item titles, hard-code the virtual name. This is what /referanser does — note that the same name goes on both the <source> and the <img>:

<picture>
  <source srcset="#item.Url#/#item.Image1#/500x400x1/Oslo-systemutvikling.jpg" type="image/jpg">
  <img src="#item.Url#/#item.Image1#/500x400x1/Oslo-systemutvikling.jpg" alt="..." />
</picture>

Every reference image is then served as Oslo-systemutvikling.jpg.

4. Match the extension to the output. These examples serve JPEG, so the virtual name ends in .jpg. Use the extension that matches the image type you are actually serving.

5. Fix the alt text while you are there. Image SEO is filename + alt + surrounding text working together. The template defaults you will often inherit — alt="photo-10", alt="profile-07" — say nothing. Set alt to the same descriptive value, e.g. alt="#f.Title#", so the filename and the alt reinforce each other.

6. Note: linkImage() does not take a virtual name. docly.linkImage(field, w, h, mode) produces a valid scaled link but names the file for you, so build the four-segment path by hand (as above) whenever you want to control the SEO name. For a CSS background image, build the same path with a leading ~ so Docly rewrites it at publish time: style="background-image:url('~#p.Url#/#p.File#/1024x768x1/virtual-name.jpg')". See Linking images and files in hash for the full set of linking forms.

Live examples in production: /tjenester names each thumbnail after its article title, and /referanser uses a fixed keyword across the listing. Getting the page URL itself clean matters for the same reason — see Omit file extensions in links.