图像
了解 Jamdesk 如何处理图像尺寸、说明文字、明暗主题变体和支持的格式，让文档视觉内容清晰易读。
Jamdesk 会为图像添加圆角并保持统一间距。将文件放入 /images 目录，然后使用标准 Markdown 引用。
屏幕截图显示的是英文界面。
标准 Markdown
使用熟悉的  语法：
路径从项目根目录开始。例如，位于 your-docs/images/screenshot.webp 的图像应引用为 /images/screenshot.webp。
图像尺寸
在图像 URL 后追加 =WIDTHxHEIGHT（中间用空格分隔）即可控制尺寸：
只设置一个尺寸，另一个尺寸会按比例缩放：
如果你希望同一列中的屏幕截图具有一致宽度，或需要将高分辨率图像缩小到合理的显示尺寸，这种方式会很有用。
说明文字
将图像包裹在 <Frame> 组件中，即可为其添加边框和底部说明文字：
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame 会在图像周围绘制细边框，并将说明文字放在下方。它不仅适用于图像，也适用于其中的任何内容。
明暗主题
文档网站通常需要为每种配色方案使用不同的图像变体：白色背景上的徽标在深色模式下看起来不协调。
srcDark 属性
最简单的方法。Jamdesk 会根据当前主题切换图像源：
<img
src="/_jd/images/logo-light.webp?v=mst25htz"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>浏览器只会加载与当前配色方案匹配的图像。
HTML <picture> 元素
如果你需要在 Jamdesk 之外也能使用的标准 HTML，可以结合媒体查询使用 <picture>：
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mst25htz" alt="Company logo" />
</picture><picture> 方式会遵循操作系统的配色方案设置。srcDark 属性则响应 Jamdesk 的主题切换按钮，这通常更适合文档网站。
支持的格式
| 格式 | 适用场景 | 备注 |
|---|---|---|
| PNG | 屏幕截图、UI 捕获 | 无损质量，支持透明度。文件较大。 |
| JPEG | 照片 | 压缩效果好，不支持透明度。 |
| SVG | 图标、图表、徽标 | 矢量格式，可缩放到任意尺寸且不会损失质量。文件极小。 |
| GIF | 简单动画 | 文件可能迅速变大。超过几帧时，可考虑使用较短的 .mp4 循环。 |
| WebP | 通用场景 | 在相近质量下比 PNG 和 JPEG 更小。所有现代浏览器均支持。 |
对于大多数文档图像，WebP 能提供最佳的大小与质量平衡。如果需要透明度，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 转换，这样你提交的任何 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。