Skip to content

Insert images

Add images to topics by uploading a file, pasting, dragging-and-dropping, or linking a URL.

Add an image by URL

  1. Place your cursor where you want the image.

  2. Type / and select Image.

  3. Enter the image URL and confirm. The image appears at the cursor.

Upload by paste or drag-and-drop

Uploading sends the file to storage and inserts the resulting hosted image:

  • Paste: Copy an image to your clipboard and press Cmd+V in the editor. The image uploads automatically and a progress placeholder shows while it transfers.

  • Drag-and-drop: Drag an image file from Finder (or any folder) onto the spot in the editor where you want it.

Image limits

  • Maximum file size: 5 MB for each uploaded image

  • Supported upload formats: PNG, JPG, GIF, WebP

The uploader rejects images larger than 5 MB and any file type outside PNG, JPG, GIF, and WebP. Resize or compress large images, and convert other formats, before adding them.

Use WebP format for the best balance of quality and file size. WebP images are typically 25-35% smaller than equivalent PNGs or JPGs, which helps your published pages load faster.

Edit a selected image

Select an image to reveal its editing controls. Quick actions appear in the floating image toolbar above the image; the full set lives in the Image panel on the right.

Control

Toolbar

Image panel

Alignment (left, center, right)

Yes

Yes

Size (50%, 75%, full width)

Yes

Yes (50%, 75%, 100%)

Inline or block placement

Yes

Yes

Caption (add or remove)

Yes

Yes (edit text)

Alt text

Opens the panel

Edit directly

Replace the image file

Yes

Yes

Download the image

No

Yes

Delete the image

Yes

Yes

Alt text and accessibility

Every image should have alt text so screen readers can describe it. In the Image panel, type a description in the Alt text field, or click Generate to have AI draft one from the image and the surrounding topic. The generated text is a starting point. Review and edit it before relying on it. When alt text is missing, the alt-text control in the image toolbar is highlighted as a reminder.

Captions, size, and placement

  • Caption: a visible figure caption rendered below the image.

  • Size: constrain the image to 50%, 75%, or 100% of the content width.

  • Placement: Block puts the image on its own line; Inline flows it with surrounding text. Placement maps to the DITA @placement attribute on export.

Images in published sites

Images render at their set size, constrained to the content width. On mobile, they scale down to fit the viewport.

See also

Was this page helpful?