# 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: - Fast, cached delivery for all uploaded images. - Responsive sizing with preserved aspect ratio. - Built-in support for accessibility via required `alt` text. Uploaded images are stored in your documentation's [media library](/content/docs/write-and-publish/media-library/index.html), so you can reuse, replace, and manage them from one place. You can add images in two ways: - **Web Editor:** Insert and manage images visually. - **Code Editor / MDX:** Use the `` component with explicit props. Images can also be combined with other layout components such as [``](/content/docs/components/card/index.html) (via its `image` prop) and [``](/content/docs/components/columns/index.html) 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](/content/docs/write-and-publish/web-editor/index.html). 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 - **Media tab:** Open the **Media** tab in the editor's secondary navbar, hover an image, and click **Insert into page**, or drag the tile onto the page. - **Paste or drop:** Paste an image from the clipboard or drop an image file onto the page. The image dialog opens so you can name the file and add alt text before it is inserted. 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: - **Top-left badge:** Shows current image dimensions (width × height). - **Side drag handles:** Drag horizontally from the left or right edge to resize the width; height adjusts automatically to preserve aspect ratio. - **Top-right toolbar:** - **Alignment icon:** Align the image (for example, left, center, or right). - **Zoom icon:** Open the image in full size. - **Trash icon:** Remove the image from the page. ### 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 ``, ``, or additional `` blocks. ### Replace an image To update an image everywhere it is used without editing any page, open it in the [media library](/content/docs/write-and-publish/media-library#how-to-update-a-file-everywhere-it-is-used/index.html) 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](/content/docs/write-and-publish/code-editor/index.html)), use the `` component to add images directly in code. ### Basic usage ``` Description of the image ``` 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](/content/docs/write-and-publish/media-library#code-editor-git/index.html) 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: - **src**: Absolute image URL. Prefer CDN URLs, including those copied from the Web Editor. - **alt**: Descriptive text for accessibility and SEO. This is read by screen readers and shown when the image cannot load. - **width**: Image width in pixels. Helps optimize layout and prevent layout shift. - **height**: Image height in pixels. Used with `width` to reserve space and reduce layout shift. - **style**: Inline CSS styles for alignment, sizing, and positioning. Use for custom layout behavior. - **priority**: Load the image immediately instead of lazy loading. Use for above-the-fold images only (default: `false`). - **fetchpriority**: Browser loading priority: `high`, `low`, or `auto`. Use `high` for critical images such as hero banners. ### Alignment and sizing example ``` Center aligned image ``` Center aligned abstract pattern You can combine `` with layout components like [``](/content/docs/components/columns/index.html) or include an image in a [``](/content/docs/components/card/index.html) 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: ``` Hero banner showing product features ``` 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: ``` External image description ``` 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 - **URL format:** Only absolute URLs are supported. - **Alt text:** Required for all images (for accessibility and SEO). - **Supported formats:** JPEG, PNG, GIF, WebP, SVG, ICO, HEIC/HEIF, AVIF, BMP, TIFF. - **Per-file limit:** 10 MB on every plan. Compress or resize larger images before uploading. - **SVG:** Scanned on upload. SVGs containing scripts, event handlers, or embedded documents are rejected. - **CDN:** Images uploaded via the Web Editor are automatically optimized and cached, and served from `blob-cdn.documentation.ai`. - **Replace:** Keeps the URL. Same format only.