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. On the published site an image written inside a sentence stays inline in that paragraph; in a CMS page body an image is always a block of its own, so one written mid-sentence splits the paragraph around it on import. The one line an image must never share is a heading’s: in a CMS page body, ##  Title removes the whole heading, text included, so give the image a line of its own.
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.
Alt text is plain text. Markdown inside it is not rendered: the editor escapes [, ], =, *, _ and backticks in it when it writes the image, so the alt reads back exactly as you typed it. A backslash directly before the closing ]( is literal, so  has the alt C:\dir\ and ends there.
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 after the closing parenthesis, either directly or after a space:
{.rounded}
{data-assetid="aaa123"}Images read the full attribute grammar, so the .class shorthand works here — which is not true of tables, lists or blockquotes. An id does not: {#hero} or {id="hero"} is dropped from an image, as it is from every element. Further groups glued to the first one are the image’s too, and when two groups set the same attribute the first one written wins, while classes add up. 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 |
href | The destination of a linked image, taken from the link around it | You, by wrapping the image in a link | Yes |
class | A hook for your own CSS | You | No |
id | — | You | Never supported: dropped on import and on the site |
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 rows marked Yes come back. When an image arrives over MCP or through an import, the write’s warning names exactly the keys it dropped and identifies the block as an image. The kept attributes are never reported, so an image carrying only data-id, data-assetid and data-responsiver produces no warning at all.
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.
In a CMS page body a linked image is one image block: the link’s destination is stored as the image’s href, and the editor writes it back in the form shown above. A title on the link, a group attached to the link’s closing parenthesis, and anything other than a data-id in a group written after the link are not kept, and the write reports them as dropped content. A link whose destination uses javascript:, vbscript:, data: or file: is refused, in the editor and on the site, so the image renders alone with no link. An image’s own source is held to the same rule, except that it may be a data:image/ PNG, JPEG, GIF or WebP.
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.