In the CMS you never type an image. You use Insert Asset, pick a file from the asset library, and set the size and the caption in the image block’s settings dialog. This page is the format that dialog writes — and, just as importantly, what the site build does to an <img> after the markdown has been turned into HTML.
Basic image
<img src="https://example.com/photo.jpg" alt="Alt text">An image that is alone on its line is not wrapped in a paragraph. Leed suppresses the <p> for that case specifically, which is what lets an image be laid out and spaced as a block rather than as a run of text. An image written inside a sentence stays inline in that paragraph, exactly as you would expect.
Alt text
The text in the square brackets is the alt text. It is what a screen reader announces and what a browser shows if the file fails to load; it is not displayed on the page when the image loads normally.
Sizing
Add =WIDTHxHEIGHT to the end of the alt text, still inside the square brackets. Values are pixels, and they become width and height attributes on the <img>.
| You write | Output attributes |
|---|---|
 | width="300" height="200" |
 | width="300" — the height scales with the image’s own aspect ratio |
 | height="200" — the width scales |
 | neither; the image is laid out at its natural size |
A width you set here also caps the responsive ladder described under Responsive rewrite: the build only offers variants at or below the width you asked for.
Captions and figures
Give the image a quoted title and it renders as a <figure> with a <figcaption>:
<figure><img src="photo.jpg" alt="Alt text"><figcaption>Figure caption</figcaption></figure>A figure is produced only when a title is present. With no title you get a bare <img>, which is the common case. Captions are parsed as inline markdown, so "Revenue growth, **Q3** — *preliminary*" renders its bold and italic.
A caption is a design element, not free metadata. In Leed’s documentation stylesheet a figure that contains a figcaption picks up a border and a fit-to-content frame, so adding a caption visibly changes the shape of the page. Write one where it carries information the surrounding prose does not; do not restate the alt text, and do not caption every image out of habit.
Attributes
Attributes go in braces immediately after the closing parenthesis, with no space:
{.rounded}
{data-assetid="aaa123"}Images route through the general attributes plugin, so the .class and #id shorthands work here — which is not true of tables, lists or blockquotes. Attributes explains why the accepted syntax differs by element, and it is worth reading before you assume a form that works on an image works everywhere.
When a caption is present the attributes land on the <img> inside the <figure>, not on the <figure> itself.
The editor re-emits a deliberately short list of attributes when it saves a page, and everything else you wrote by hand is dropped at that point:
| Attribute | Meaning | Written by | Survives a save? |
|---|---|---|---|
data-assetid | The asset library id this image came from | The asset picker | Yes |
data-id | The block’s stable address, used by MCP edits | The editor, automatically | Yes |
data-responsiver="false" | Opt this image out of the responsive rewrite | The editor, for SVGs | Yes |
class | A hook for your own CSS | You | No |
id | A link target | You | No |
any other data-* | Whatever your templates read | You | No |
The complete list of what an editor save discards is on Fidelity and Unsupported Syntax; the short version is that only the three rows above come back.
Linked images
Wrap the image in a link to make it clickable:
[](https://example.com)
[](pageid:17b52470-bbb5-4e90-a1b5-70c097296c72)The pageid: form resolves the same way any internal link does — see Links and Internal Links for what happens when the target page is not published.
What happens after the markdown
Markdown gets you an <img>. Three further steps run over the built HTML before it ships, and they explain most of what you will see in a published page’s source.
Responsive rewrite
Every img that is not a direct child of a <picture> gets a srcset across six widths plus sizes="100vw". The build produces the variant URL by substituting the variant name into the image URL, so this works on asset-manager images and is undone again for anything else: if the original URL does not contain /cdn-cgi/imagedelivery/, the srcset and sizes are stripped back off and the image keeps its single source.
Four other conditions also skip an image: an explicit data-responsiver="false", an existing srcset you wrote yourself, a .svg source, and a data: URI placeholder.
| Name | Used for |
|---|---|
small | the narrowest responsive step |
medium | small screens |
large | tablet and small laptop |
xl | full-width on a laptop |
xxl | large and high-density displays |
original | the unresized upload; also the name substituted out to build the others |
social | Open Graph and Twitter card images |
socialtiny | small social thumbnails |
profile | avatars |
profiletiny | inline avatars |
The pixel width behind each name, and how to request one directly, belong to Image Variants and Responsive Images. What matters when you are writing markdown is that one ![]() becomes a full responsive set without you asking, and that these are the names it uses.
Opting out
Set data-responsiver="false" on the image and it keeps exactly the source you gave it. The editor writes this automatically for SVGs, which have no meaningful pixel variants; the build skips .svg sources anyway, so the attribute is belt and braces rather than the only guard.
Image URLs are rewritten
When the editor serializes an image whose source is https://imagedelivery.net/<path>, it writes /cdn-cgi/imagedelivery/<path> into the markdown instead. Your content therefore never carries the delivery domain, and the same page can be served from a preview host, a custom domain and the platform domain without a find-and-replace. The build puts a domain back on at the end when a site is configured to emit absolute URLs.
Click to zoom
On documentation pages, every image inside the article body gets a click-to-zoom handler that opens it in a full-screen viewer with pan and zoom controls. Nothing needs to be switched on. The one exception is the linked-image case above: an image whose parent is an <a> is skipped. The reading experience that provides this viewer is described on Documentation Reading Experience.
Where the URL and the asset id come from
You will not type either. Uploading a file, and the crops, formats and size limits that apply before an image is ever referenced, are covered by Uploading Images; picking one and getting back both its URL and its data-assetid is what Asset Library is for. Inserting one in the editor — along with video, audio and iframes, which are not image syntax — is Inserting Media and Embeds, and the markdown for those is Embeds and Icons.