跳转到主要内容
在文档中添加图片、嵌入视频，并通过 iframes 引入交互式内容。
一张风景照片：前景为紫色花朵，远处是群山，天空湛蓝，点缀着零散白云。

​
图像

在文档中添加图像，以提供可视化的 context、示例或装饰。

​
基本图像语法

使用 Markdown 语法向文档中添加图像：
图像路径相对于文档仓库的根目录。例如，如果你的图像位于仓库中的 images/screenshot.png，则路径为 /images/screenshot.png。不支持相对路径（例如 ./screenshot.png）。
请务必包含具有描述性的 alt 文本，以提升可访问性和 SEO（搜索引擎优化）。alt 文本应清晰说明图像所呈现的内容。
图像文件必须小于 20 MB。对于更大的文件，请将其托管在 Amazon S3 或 Cloudinary 等 CDN 服务上。

​
HTML 图像嵌入

若需更精准地控制图像显示，请使用 HTML 的 <img> 标签：

​
调整图片尺寸

使用 Tailwind CSS 类来调整图片尺寸。当没有工具类能满足所需尺寸时，请使用任意值（arbitrary value），例如 w-[450px]：
避免使用 style prop 来调整尺寸。它可能在页面加载时导致布局偏移。

​
禁用图片缩放

要禁用图片点击时的默认缩放，请添加 noZoom 属性：
要让图片可点击并指向链接，请将图片包裹在 a（锚点）标签中，并添加 noZoom 属性：
位于锚点标签内的图像会自动显示指针光标，表示它们可点击。

​
复制和下载操作

使用 actions 属性为图像添加复制和下载控件。启用后，读者将鼠标悬停、聚焦或触摸图像时会显示浮层按钮，可将图像复制到剪贴板或保存到设备。 将 actions 设为 true 可同时显示两个按钮，或传入以逗号分隔的列表以启用特定操作：
actions 支持的值：
  • copy：将图像复制到剪贴板。
  • download：将图像下载为文件。
使用 actionsPlacement 属性调整按钮位置。默认值为 bottom-center。
actionsPlacement 支持的值：bottom-center、bottom-left、bottom-right、top-center、top-left、top-right。

​
明暗模式的图像

要在浅色和深色主题下显示不同的图像，请使用 Tailwind CSS 类：

​
自动图片优化

Mintlify 在提供存储于你文档仓库中的图片时会对其进行优化。你无需自行转换格式、生成多种尺寸或设置尺寸。 优化适用于你使用根相对路径引用的图片，例如 /images/screenshot.png。这包括 Markdown 图片、<img> 标签、组件上的图片和图标属性，以及 docs.json 中的 logo、背景和 favicon。 对于每张经过优化的图片，Mintlify 会：
  • 向支持的浏览器提供 AVIF 或 WebP 格式，向不支持的浏览器提供原始格式。
  • 压缩图片并移除元数据，例如 EXIF 数据。
  • 生成最宽 2500px 的多种尺寸版本，以便浏览器下载适合页面布局的最小版本。图片永远不会被放大到超过原始尺寸。
  • 为图片添加原始宽度和高度，以避免图片加载时页面发生偏移。如果你在 <img> 标签上设置了 width 或 height，Mintlify 会改用你设置的值。
Mintlify 会按仓库中的原样提供以下图片，不进行优化：
  • GIF，以确保动画正常播放。
  • SVG 和 ICO 文件。
  • 使用绝对 URL 引用的图片，例如托管在外部 CDN 上的图片。
  • 需要身份验证的页面上的图片。
在将 GIF 和外部托管的图片添加到文档之前先进行压缩。当你更新仓库中的图片文件时，Mintlify 会通过新的 URL 提供新版本，因此读者不会看到旧图片的缓存副本。

​
SVG 图像

在包含 foreignObject 元素的 SVG 文件中，生产环境下的渲染效果会和本地开发环境不同。出于安全考虑，Mintlify 的图像 CDN 会从 SVG 中移除 foreignObject，这可能会截断或隐藏文本以及其他嵌入的 HTML 内容。 这通常会影响从诸如 draw.io 等工具导出的 SVG，尤其是在启用了 HTML 文本格式或自动换行时。要解决这个问题，请在导出 SVG 之前，关闭图中所有标签的 Formatted Text 和 Word Wrap 选项。更多有关 SVG 导出的信息，请参阅 draw.io 文档。

​
视频

Mintlify 支持在 Markdown 中使用 HTML 标签，让你能更灵活地创建丰富内容。
请务必在 video 元素内提供备用文本内容，以便在不支持视频播放的浏览器中显示。

​
嵌入 YouTube 视频

使用 iframe 元素嵌入 YouTube 视频：

​
自托管视频

对于自托管视频对象，请使用 HTML <video> 元素：

​
自动播放视频

要让视频自动播放，请使用：
使用 JSX 语法时，将由两个单词组成的属性写成驼峰命名（camelCase）：autoPlay、playsInline、allowFullScreen。

​
Iframe

使用 iframe 元素嵌入外部内容：
将 iframe 包裹在 frame 组件中，可使其保持在文本列宽内并避免溢出。

Frame 组件参考

了解如何使用 Frame 组件来呈现图像。