Images - Documentation.AI

Images

Reference for adding images using the editor UI and the Image component.

Overview

Use images to illustrate concepts, show UI, and make your documentation easier to scan. Documentation.AI automatically optimizes images uploaded through the Web Editor and serves them from a CDN, so you get:

Uploaded images are stored in your documentation's media library, so you can reuse, replace, and manage them from one place.

You can add images in two ways:

Images can also be combined with other layout components such as <Card> (via its image prop) and <Columns> to build richer page layouts.

Using with Web Editor

Use the Web Editor to insert and manage images without writing code. For more on the editor itself, see Web Editor.

Sample image abstract pattern with colorful shapes

Insert an image

  1. Place your cursor on a new line.
  2. Type / to open the command menu.
  3. Select Image.
  4. In the Select image dialog, either:
    • Click the Upload tile, choose a file from your computer, confirm or edit its name, and click Upload, or
    • Search and select an image that is already in your media library.
  5. Click Insert image.

The Select image picker. Upload a new image or pick one from the library.

The selected image is inserted into the page and served from an optimized CDN. Its alt text defaults to the alt text saved in the media library, or the file name.

Other ways to insert

If you upload an image that already exists in the library, the existing file is reused instead of being stored twice.

Prefer writing in code?

You can switch to MDX view inside the Web Editor to write or edit this component using the same syntax as the Code Editor. This is useful if you want full control while staying in the Web Editor.

Resize, align, and manage the image

Hover over an image to reveal controls:

Edit image properties

  1. Hover over the image and click the three-dot menu in the top-right corner.
  2. In Image properties, you can update:
    • Image URL: The full CDN URL for the uploaded image.
    • Caption: Optional text displayed below the image.
    • Alt text: Required descriptive text for accessibility and SEO.

The alt text field is mandatory for SEO and accessibility. Describe what is in the image, not just the file name.

You can copy the image URL from image properties and reuse it in other components, such as <Card image="...">, <Columns>, or additional <Image> blocks.

Replace an image

To update an image everywhere it is used without editing any page, open it in the media library and click Replace file. The URL stays the same, so every page and component that references it shows the new version once the CDN refreshes, usually within a minute. The replacement must be the same format as the original.

Using with Code Editor

When editing pages as MDX (for example in the Code Editor), use the <Image> component to add images directly in code.

Basic usage

<Image
  src="https://blob-cdn.documentation.ai/org-.../doc-.../1757300000000-abc123-dashboard-overview.png"
  alt="Description of the image"
  width="800"
  height="600"
/>

To get a URL for an uploaded image, open the Media tab in the web editor, hover the image, and click Copy URL. See Media library for the Git-based workflow.

Abstract geometric pattern with colorful shapes

The alt attribute is required. Provide concise, descriptive text that explains the image content to screen readers.

Key props

Use these props to control how images render:

Alignment and sizing example

<Image
  src="https://your-cdn.com/image.png"
  alt="Center aligned image"
  width="400"
  height="300"
  style="width: 400px; height: auto; margin: 0 auto;"
/>

Center aligned abstract pattern

You can combine <Image> with layout components like <Columns> or include an image in a <Card> via its image prop to create more complex grids and feature blocks.

Advanced options

Performance and loading behavior

Use priority and fetchpriority to fine-tune how critical images load:

<Image
  src="https://your-cdn.com/hero-image.png"
  alt="Hero banner showing product features"
  width="1200"
  height="600"
  priority={true}
  fetchpriority="high"
/>

Reserve performance options for above-the-fold or otherwise critical images. Overusing priority or fetchpriority="high" can hurt overall page performance.

External URLs

You can reference external images directly in MDX:

<Image
  src="https://external-cdn.com/image.jpg"
  alt="External image description"
  width="600"
  height="400"
/>

External images are not optimized by Documentation.AI's CDN. Whenever possible, upload images through the Web Editor and reuse their CDN URLs for better caching and performance.

Specifications