mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
6c53a28e3a
* Document className and Tailwind arbitrary value support All built-in components now accept a className prop (mint#10540), and dynamic Tailwind utilities work in className on MDX components (mint#6737). Two pages stated the opposite. - Correct the claims that Tailwind arbitrary values are unsupported in customize/custom-scripts and guides/custom-layouts - Add className and arbitrary value guidance to the Tailwind section of custom-scripts, including the runtime-class limitation and the Tab content-panel caveat - Add a Style components section to the components overview - Add className property rows to every component reference page that supports it, and note the three components that do not - Document inline Markdown support in component title props - Correct the callouts page, which said typed callouts accept only children - Replace inline style resizing with Tailwind classes in image embeds - Add a help center article for Tailwind classes not applying in the editor's live preview, and note the limitation in custom-layouts - Point skill.md at className before custom.css - Accept className, keyframes, and unstyled in the Vale vocabulary Resolves DOC-316, DOC-317 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Apply batched suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> * Apply batched suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
253 lines
6.7 KiB
Plaintext
253 lines
6.7 KiB
Plaintext
---
|
|
title: "Images and embeds"
|
|
description: "Add images, embed YouTube videos, and include iframes in your MDX pages to enhance documentation with visual and interactive media content."
|
|
keywords: ["images", "videos", "iframes", "media", "svg"]
|
|
---
|
|
|
|
Add images, embed videos, and include interactive content with iframes to your documentation.
|
|
|
|
<Frame>
|
|
<img
|
|
className="rounded-xl"
|
|
src="https://mintlify-assets.b-cdn.net/bigbend.jpg"
|
|
alt="Photograph of a scenic landscape with purple flowers in the foreground, mountains in the background, and a blue sky with scattered clouds."
|
|
/>
|
|
</Frame>
|
|
|
|
## Images
|
|
|
|
Add images to provide visual context, examples, or decoration to your documentation.
|
|
|
|
### Basic image syntax
|
|
|
|
Use [Markdown syntax](https://www.markdownguide.org/basic-syntax/#images) to add images to your documentation:
|
|
|
|
```mdx
|
|
|
|
```
|
|
|
|
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.
|
|
|
|
<Tip>
|
|
Always include descriptive alt text to improve accessibility and SEO. The alt text should clearly describe what the image shows.
|
|
</Tip>
|
|
|
|
Image files must be less than 20 MB. For larger files, host them on a CDN service like [Amazon S3](https://aws.amazon.com/s3) or [Cloudinary](https://cloudinary.com).
|
|
|
|
### HTML image embeds
|
|
|
|
For more control over image display, use HTML `<img>` tags:
|
|
|
|
```jsx
|
|
<img
|
|
src="/images/dashboard.png"
|
|
alt="Main dashboard interface"
|
|
className="w-[400px] h-[300px] rounded-lg"
|
|
/>
|
|
```
|
|
|
|
#### Resize images
|
|
|
|
Use [Tailwind CSS](/customize/custom-scripts#style-with-tailwind-css) classes to resize images. When no utility class covers the size that you need, use an arbitrary value such as `w-[450px]`:
|
|
|
|
```jsx
|
|
<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.
|
|
|
|
#### Disable image zoom
|
|
|
|
To disable the default zoom on click for images, add the `noZoom` property:
|
|
|
|
```html highlight="4"
|
|
<img
|
|
src="/images/screenshot.png"
|
|
alt="Descriptive alt text"
|
|
noZoom
|
|
/>
|
|
```
|
|
|
|
#### Link images
|
|
|
|
To make an image a clickable link, wrap the image in an anchor tag and add the `noZoom` property:
|
|
|
|
```html
|
|
<a href="https://mintlify.com" target="_blank">
|
|
<img
|
|
src="/images/logo.png"
|
|
alt="Mintlify logo"
|
|
noZoom
|
|
/>
|
|
</a>
|
|
```
|
|
|
|
<Note>
|
|
Images within anchor tags automatically display a pointer cursor to indicate they are clickable.
|
|
</Note>
|
|
|
|
#### Copy and download actions
|
|
|
|
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:
|
|
|
|
```html
|
|
<img
|
|
src="/images/diagram.png"
|
|
alt="System architecture diagram"
|
|
actions
|
|
/>
|
|
```
|
|
|
|
```html
|
|
<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`.
|
|
|
|
```html
|
|
<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`.
|
|
|
|
#### Light and dark mode images
|
|
|
|
To display different images for light and dark themes, use Tailwind CSS classes:
|
|
|
|
```html
|
|
<!-- 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 images
|
|
|
|
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](https://www.drawio.com) 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](https://www.drawio.com/doc/faq/svg-export-text-problems) for more information on SVG exports.
|
|
|
|
## Videos
|
|
|
|
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html), giving you flexibility to create rich content.
|
|
|
|
<Tip>
|
|
Always include fallback text content within video elements for browsers that don't support video playback.
|
|
</Tip>
|
|
|
|
### YouTube embeds
|
|
|
|
Embed YouTube videos using iframe elements:
|
|
|
|
```html
|
|
<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>
|
|
```
|
|
|
|
<Frame>
|
|
<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>
|
|
</Frame>
|
|
|
|
### Self-hosted videos
|
|
|
|
Use the HTML `<video>` element for self-hosted video content:
|
|
|
|
```html
|
|
<video
|
|
controls
|
|
className="w-full aspect-video rounded-xl"
|
|
src="link-to-your-video.com"
|
|
></video>
|
|
```
|
|
|
|
### Autoplay videos
|
|
|
|
To autoplay a video, use:
|
|
|
|
```html
|
|
<video
|
|
autoPlay
|
|
muted
|
|
loop
|
|
playsInline
|
|
className="w-full aspect-video rounded-xl"
|
|
src="/videos/demo.mp4"
|
|
></video>
|
|
```
|
|
|
|
<Note>
|
|
When using JSX syntax, write double-word attributes in camelCase: `autoPlay`, `playsInline`, `allowFullScreen`.
|
|
</Note>
|
|
|
|
## Iframes
|
|
|
|
Embed external content using iframe elements:
|
|
|
|
```html
|
|
<iframe
|
|
src="https://example.com/embed"
|
|
title="Embedded content"
|
|
className="w-full h-96 rounded-xl"
|
|
></iframe>
|
|
```
|
|
|
|
<Tip>
|
|
Wrap iframes in a [frame](/components/frames) component to keep them within the text column width and prevent overflow.
|
|
|
|
```html
|
|
<Frame>
|
|
<iframe
|
|
src="https://example.com/embed"
|
|
title="Embedded content"
|
|
className="w-full h-96 rounded-xl"
|
|
></iframe>
|
|
</Frame>
|
|
```
|
|
</Tip>
|
|
|
|
## Related resources
|
|
|
|
<Card title="Frame component reference" icon="frame" horizontal href="/components/frames">
|
|
Learn how to use the Frame component for presenting images.
|
|
</Card>
|