linkImage(embeddedId, [width], [height], [mode], [filename]) Last updated: 10. Jul 2026
Creates a link to an image within a document, building a WxHxM image URL. Only works from site display templates for documents.
linkImage accepts an optional 'filename' argument (the last URL segment, the SEO display name). The extension on that filename decides BOTH the public filename and the output format: .jpg/.jpeg, .png, .webp and .avif steer the conversion to that format, while .gif and .svg are not converted. WebP/AVIF output requires images.sizePolicy "auto" or "strict" in site.json — the default "open" policy does not support WebP/AVIF and serves such a link as JPEG. linkImage URL-encodes the SEO name for you and replaces spaces with hyphens, so pass the raw title. See Image output formats for how to choose a format, and the KB article Adopt AVIF and WebP image formats for the <picture> markup AVIF requires (there is no Accept-header negotiation).
Two overloads exist:
linkImage(embeddedId, width, height [, mode] [, filename])
linkImage(fileObject, embeddedId, width, height [, mode] [, filename])
The second overload prepends fileObject.Url, replacing the #f.Url#/#f.Image1#/… pattern in listings. An options object also works: linkImage(f.Image1, { width: '1200', height: '800', filename: 'produkt.webp' }).
Under images.sizePolicy: "auto", the sizes you request are discovered automatically, and the folder 'Image sizes' Scan finds literal linkImage calls in your source. Client-JS-generated URLs are not discovered and must be added to allowedSizes manually. The WxHxM sizes you request here are enforced by images.sizePolicy — under "strict" an unregistered size returns HTTP 400. See the 'Image scaling & allowed sizes' section on the Image scaling page, and the KB article Restrict and register image sizes for how to enable the policy and register your sizes.
See also: linkFile Image scaling Path traversal
Parameters
| Name | Type | Description |
|---|---|---|
| embeddedId | string | ID of the embedded image resource you want to generate a reference to. |
| width (optional) | number | Target width for scaling (behaviour varies, see specified mode) |
| height (optional) | number | Target height for scaling (behaviour varies, see specified mode) |
| mode (optional) | number | See list and description of modes: |
| filename (optional) | string | The SEO display name (last URL segment). Its extension selects the output format: .jpg/.jpeg, .png, .webp, .avif convert to that format; .gif/.svg are not converted. linkImage URL-encodes this and swaps spaces for hyphens, so pass the raw title. See Image output formats. |
Returns
A working link to the specified image and scaling.
Example
Code example (#JS)
#JS is mixed HTML (or other text file) with inline JavaScript with # starting and ending each inline statement.When using src attributes:
<img src="#docly.linkImage(Image1, 160, 120, 1)#" alt="Image" />
With an SEO name and an explicit output format (extension picks the format):
<img src="#docly.linkImage(Image1, 1200, 800, 0, 'produktnavn.webp')#" alt="Image" />
In a listing, the fileObject overload prepends item.Url:
#for (let item of Items) {#
<img src="#docly.linkImage(item, item.Image1, 500, 400, 1, item.Title + '.webp')#" alt="#enc(item.Title)#" />
#}#
AVIF must sit inside a <picture> with a WebP/JPEG fallback (no Accept-header negotiation):
<picture>
<source type="image/avif" srcset="#docly.linkImage(Image1, 1200, 800, 0, 'produktnavn.avif')#">
<source type="image/webp" srcset="#docly.linkImage(Image1, 1200, 800, 0, 'produktnavn.webp')#">
<img src="#docly.linkImage(Image1, 1200, 800, 0, 'produktnavn.jpg')#" width="1200" height="800" alt="Image">
</picture>
When using style background image or other plugins:
<div style="background-image:url('~#docly.linkImage(Image1, 160, 120, 1, 'seo-name.webp')#')"></div>
Plugin example:
<div data-plugin-image="~#docly.linkImage(Image1, 160, 120, 1)#"></div>Output
The #JS code above produces the output shown below:No demo available.