图片与嵌入

在 MDX 页面中添加图片、嵌入 YouTube 视频和 iframe，以视觉和互动内容丰富文档。

在文档中添加图片、嵌入视频，并通过 iframes 引入交互式内容。

图像

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

基本图像语法

使用 Markdown 语法向文档中添加图像：

![描述图像的替代文本](/images/screenshot.png)

图像路径相对于文档仓库的根目录。例如，如果你的图像位于仓库中的 images/screenshot.png，则路径为 /images/screenshot.png。不支持相对路径（例如 ./screenshot.png）。

请务必包含具有描述性的 alt 文本，以提升可访问性和 SEO（搜索引擎优化）。alt 文本应清晰说明图像所呈现的内容。

图像文件必须小于 20 MB。对于更大的文件，请将其托管在 Amazon S3 或 Cloudinary 等 CDN 服务上。

HTML 图像嵌入

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

<img 
  src="/images/dashboard.png" 
  alt="主控制台界面"
  style={{height: "300px", width: "400px"}}
  className="rounded-lg"
/>

使用内联样式调整图片尺寸

使用 style 属性在 JSX 中编写内联样式来调整图片尺寸：

<img
  src="/images/architecture.png"
  style={{width: "450px", height: "auto"}}
  alt="系统架构图"
/>

禁用图片缩放

要禁用图片点击时的默认缩放，请添加 noZoom 属性：

<img 
  src="/images/screenshot.png" 
  alt="描述性替代文本"
  noZoom
/>

链接图片

要让图片可点击并指向链接，请将图片包裹在 a（锚点）标签中，并添加 noZoom 属性：

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

位于锚点标签内的图像会自动显示指针光标，表示它们可点击。

复制和下载操作

使用 actions 属性为图像添加复制和下载控件。启用后，读者将鼠标悬停、聚焦或触摸图像时会显示浮层按钮，可将图像复制到剪贴板或保存到设备。

将 actions 设为 true 可同时显示两个按钮，或传入以逗号分隔的列表以启用特定操作：

<img
  src="/images/diagram.png"
  alt="系统架构图"
  actions
/>

<img
  src="/images/diagram.png"
  alt="系统架构图"
  actions="copy,download"
/>

actions 支持的值：

copy：将图像复制到剪贴板。
download：将图像下载为文件。

使用 actionsPlacement 属性调整按钮位置。默认值为 bottom-center。

<img
  src="/images/diagram.png"
  alt="系统架构图"
  actions="download"
  actionsPlacement="top-right"
/>

actionsPlacement 支持的值：bottom-center、bottom-left、bottom-right、top-center、top-left、top-right。

明暗模式的图像

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

<!-- 浅色模式图片 -->
<img 
  className="block dark:hidden" 
  src="/images/light-mode.png" 
  alt="浅色模式界面"
/>

<!-- 深色模式图片 -->
<img 
  className="hidden dark:block" 
  src="/images/dark-mode.png" 
  alt="深色模式界面"
/>

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 视频：

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

自托管视频

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

<video
  controls
  className="w-full aspect-video rounded-xl"
  src="您的视频链接.com"
></video>

自动播放视频

要让视频自动播放，请使用：

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

使用 JSX 语法时，将由两个单词组成的属性写成驼峰命名（camelCase）：autoPlay、playsInline、allowFullScreen。

Iframe

使用 iframe 元素嵌入外部内容：

<iframe 
  src="https://example.com/embed" 
  title="嵌入式内容"
  className="w-full h-96 rounded-xl"
></iframe>

将 iframe 包裹在 frame 组件中，可使其保持在文本列宽内并避免溢出。

<Frame>
  <iframe 
    src="https://example.com/embed" 
    title="嵌入式内容"
    className="w-full h-96 rounded-xl"
  ></iframe>
</Frame>

Frame 组件参考

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

Frame 组件参考

On this page