Images and embeds

Add images, embed YouTube videos, and include iframes in your MDX pages to enhance documentation with visual and interactive media content.

Add images, embed videos, and include interactive content with iframes to your documentation.

Add images to provide visual context, examples, or decoration to your documentation.

Use Markdown syntax to add images to your documentation:

![Alt text describing the image](/images/screenshot.png)

Image paths are root-relative from your docs repository. For example, if your image is at images/screenshot.png in your repository, the path is /images/screenshot.png. Relative paths (for example, ./screenshot.png) are not supported.

Image files must be less than 20 MB. For larger files, host them on a CDN service like Amazon S3 or Cloudinary.

For more control over image display, use HTML <img> tags:

<img
  src="/images/dashboard.png"
  alt="Main dashboard interface"
  className="w-[400px] h-[300px] rounded-lg"
/>

Use Tailwind CSS classes to resize images. When no utility class covers the size that you need, use an arbitrary value such as w-[450px]:

<img
  src="/images/architecture.png"
  alt="Diagram showing the architecture of the system"
  className="w-[450px] h-auto"
/>

Avoid the style prop for sizing. It can cause a layout shift on page load.

To disable the default zoom on click for images, add the noZoom property:

<img 
  src="/images/screenshot.png" 
  alt="Descriptive alt text"
  noZoom
/>

To make an image a clickable link, wrap the image in an anchor tag and add the noZoom property:

<a href="https://mintlify.com" target="_blank">
  <img 
    src="/images/logo.png" 
    alt="Mintlify logo"
    noZoom
  />
</a>

Add copy and download controls to an image with the actions property. When enabled, buttons appear as an overlay on hover, focus, or touch, letting readers copy the image to their clipboard or save it to their device.

Set actions to true to show both buttons, or pass a comma-separated list to enable specific actions:

<img
  src="/images/diagram.png"
  alt="System architecture diagram"
  actions
/>

<img
  src="/images/diagram.png"
  alt="System architecture diagram"
  actions="copy,download"
/>

Supported values for actions:

• copy: Copy the image to the clipboard.
• download: Download the image as a file.

Use the actionsPlacement property to position the buttons. The default is bottom-center.

<img
  src="/images/diagram.png"
  alt="System architecture diagram"
  actions="download"
  actionsPlacement="top-right"
/>

Supported values for actionsPlacement: bottom-center, bottom-left, bottom-right, top-center, top-left, top-right.

To display different images for light and dark themes, use Tailwind CSS classes:

<!-- Light mode image -->
<img 
  className="block dark:hidden" 
  src="/images/light-mode.png" 
  alt="Light mode interface"
/>

<!-- Dark mode image -->
<img 
  className="hidden dark:block" 
  src="/images/dark-mode.png" 
  alt="Dark mode interface"
/>

SVG files that use foreignObject elements render differently in production than in local development. Mintlify's image CDN strips foreignObject from SVGs as a security measure, which can truncate or hide text and other embedded HTML content.

This commonly affects SVGs exported from tools like draw.io that have HTML text formatting or word wrap turned on. To fix this, disable Formatted Text and Word Wrap on all labels in your diagram before exporting to SVG. See the draw.io documentation for more information on SVG exports.

Mintlify supports HTML tags in Markdown, giving you flexibility to create rich content.

Embed YouTube videos using iframe elements:

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="YouTube video player"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

Use the HTML <video> element for self-hosted video content:

<video
  controls
  className="w-full aspect-video rounded-xl"
  src="link-to-your-video.com"
></video>

To autoplay a video, use:

<video
  autoPlay
  muted
  loop
  playsInline
  className="w-full aspect-video rounded-xl"
  src="/videos/demo.mp4"
></video>

Embed external content using iframe elements:

<iframe 
  src="https://example.com/embed" 
  title="Embedded content"
  className="w-full h-96 rounded-xl"
></iframe>

• Create and edit pages
• Components overview
• Migrate from GitBook