DocsUpdated 24 Oct 2026

Uploaded image

The Uploaded Image schema is used for image files. Drop an image into a folder and it gets this schema; the editor shows the image and lets you replace it. The original is stored as uploaded. To show it at another size or in another format, link it with docly.linkImage, which scales and converts it when it is requested.

The schema

Field	Type	Notes
`File`	Embedded image	The image. Stored on disk as uploaded; the field holds the embedded file id. With no image yet, the editor offers camera and paste buttons.
`Filename`	Text	The file name, shown as the heading in the editor.
`Description`	Text	Optional. Not indexed for search.
Tags	Document tags	The tag field in the form.

Property	Value
Schema name	`Uploaded Image` — a platform schema that ships with the deployment; the File storage package carries it too
Mapped extensions	`jpeg`, `jpg`, `png`, `gif`, `svg`, `webp`, `avif`, `bmp`, `tif`, `heic`, `heif`

Other image extensions, such as .tiff and .ico, are not mapped and become an Uploaded file. They are still served at their path; they just are not Uploaded Images.

Create one

Upload in the Docly editor: drag the image onto a folder.
docly CLI: docly put "<folder path>/logo.png" logo.png --create, or docly push from a working copy.

The same rules as for Uploaded file apply: developers always get the schema, other users only where the folder accepts it (File storage package or the folder's accepted content), and the editor and CLI take files up to about 4 GB.

Serving the original

The image document is served at its own path, unchanged, with a Content-Type from its extension — #/Root/assets/logo.png is /assets/logo.png. Use the plain path when you want the original, for example for an SVG icon.

<img src="/assets/logo.svg" width="160" height="40" alt="Example Ltd">

Scaled and converted links

Get the document with getFile (or a row from getFiles) and pass it first to linkImage, with File as the embedded id. The last argument is the SEO file name; its extension picks the output format.

#let p = docly.getFile("images/team.jpg")#
<img src="#docly.linkImage(p, p.File, 800, 600, 1, 'our-team.webp')#" width="800" height="600" alt="Our team">

#for (let img of docly.getFiles("images", "*", 0, null, "Uploaded Image")) {#
<img src="#docly.linkImage(img, img.File, 300, 200, 1, img.filename + '.jpg')#" width="300" height="200" alt="#docly.htmlAttributeEncode(img.filename)#">
#}#

An SVG source is served unscaled and unchanged, whatever size you ask for.
WebP and AVIF output need images.sizePolicy "auto" or "strict" in site.json; under the default "open" such a link is served as JPEG/PNG. Under "strict", a size that is not registered answers HTTP 400.
Scaling modes 0–5 are described in Image scaling, formats in Image output formats and size policies in Restrict and register image sizes.

Limits and behaviour

Cached for a year. The original at its path is a static file with a one-year max-age. Replace it under the same name and returning visitors can keep the old image — use a new name, or assetUrl() (Cache-busting bundles with assetUrl).
Not searched by content, like Uploaded File; the name and tags are.
An image that belongs to a page is better kept in an image field of that page's document than in a rich text field — see Keep images out of rich text fields.
Folder previews show the image itself — see Preview image in folder lists.

More on scaling: Scale and convert images in Docly.