图像
调整图像尺寸、添加说明、切换明暗主题版本，并选择受支持的格式，呈现清晰易读的文档视觉内容。
Jamdesk 会为图像添加圆角和统一的间距。将文件放入 /images 目录，并使用标准 Markdown 引用。
屏幕截图显示的是英文界面。
标准 Markdown
使用  语法：
路径从项目根目录开始。your-docs/images/screenshot.webp 中的图像引用路径为 /images/screenshot.webp。
图片尺寸
在图像 URL 后（以空格分隔）添加 =WIDTHxHEIGHT，即可控制尺寸：
只设置一个尺寸，另一个尺寸会按比例缩放：
可使用此语法让一列屏幕截图保持相同宽度，或缩小高分辨率图像以便显示。
说明文字
将图像放在 <Frame> 组件中，即可添加边框和显示在图像下方的图注：
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame 内可以放置任何内容，不限于图像。
点击缩放
在宽度为 768px 或更大的屏幕上，点击图像即可全屏查看。按 Escape 键或点击任意位置可关闭放大的图像。
在 <img loading="lazy"> 标签中添加 noZoom，即可禁用缩放：
<img src="/_jd/images/diagram.png?v=mwdojjfh" alt="Architecture diagram" data-no-zoom="true" />Markdown 图像（）不支持属性语法，因此无法禁用缩放。需要使用 noZoom 时，请改用 <img loading="lazy"> 标签。
明暗模式
文档网站通常需要为不同的配色方案准备不同的图像版本：白色背景上的 Logo 在深色模式下看起来会不协调。
srcDark 属性
Jamdesk 会根据当前主题切换图像来源：
<img
src="/_jd/images/logo-light.webp?v=mwdojjfh"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>浏览器只会加载与当前配色方案匹配的图像。
HTML <picture> 元素
使用带媒体查询的 <picture>，即可编写标准 HTML，并在 Jamdesk 之外使用：
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mwdojjfh" alt="Company logo" />
</picture><picture> 方案会遵循操作系统的配色方案设置。srcDark 属性则会遵循 Jamdesk 的主题切换设置。对于文档网站，通常更适合使用后者。
支持的格式
| 格式 | 适用场景 | 备注 |
|---|---|---|
| PNG | 屏幕截图、UI 截图 | 无损画质，支持透明背景。文件较大。 |
| JPEG | 照片 | 压缩效果好，不支持透明背景。 |
| SVG | 图标、图表、Logo | 矢量格式，可缩放至任意尺寸且不会损失画质。文件极小。 |
| GIF | 简单动画 | 文件可能很快变大。超过几帧时，可考虑使用较短的 .mp4 循环视频。 |
| WebP | 通用 | 在画质相近时，文件比 PNG 和 JPEG 更小。所有现代浏览器均支持。 |
对于大多数文档图像，WebP 的体积与画质比最佳。它也支持透明背景，因此无需为此使用 PNG。
最佳实践
屏幕阅读器会朗读替代文本。图像加载失败时，替代文本也会显示为占位内容。请描述图像所展示的内容。
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
对于不提供信息的装饰性图像（如背景图案、分隔线），请使用空替代文本：。
较大的图像会拖慢页面加载速度，移动网络连接下尤为明显。建议控制在以下大小：
- 屏幕截图/UI： PNG 或 WebP，小于 500KB
- 照片： JPEG 或 WebP，小于 200KB
- 图标和图表： 尽可能使用 SVG
Squoosh 和 TinyPNG 可以在不造成明显画质损失的情况下压缩图像。提交前，请使用其中一种工具处理屏幕截图。
Jamdesk 也可以在构建时压缩图像。在 docs.json 中启用自动转换为 WebP。启用后，Jamdesk 会在每次构建时优化你提交的所有 PNG 或 JPG 文件。
宽度各不相同的屏幕截图会显得杂乱。请选择一种标准截图宽度（1200px 效果不错），并在文档中统一使用。Jamdesk 会缩放图像以适应内容区域。源图尺寸一致，渲染效果也会保持一致。
Jamdesk 会为每个页面生成一张带品牌标识的 1200×630 社交卡片。可在 frontmatter 中使用 og:image 为单个页面设置其他图像。构建完成后，将页面 URL 输入免费的 OpenGraph Preview 工具，查看卡片在 X、Facebook、LinkedIn、Slack、Discord 等平台上的显示效果。完整设置说明请参阅 SEO 优化。
文件组织
将图像分组放入子目录，使目录结构与内容结构相对应：
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json使用从项目根目录开始的完整路径引用图像：
避免在图像文件名中使用空格。请改用连字符：api-response.webp，而不是 api response.webp。