图片
使用 Markdown 语法为文档添加图片，支持尺寸控制、说明文字以及浅色/深色模式。
Jamdesk 会以圆角和一致的间距渲染图片。将文件放入 /images 目录，然后使用标准 Markdown 语法引用即可。
截图显示的是英文界面。
标准 Markdown
使用熟悉的  语法：
路径从项目根目录开始。位于 your-docs/images/screenshot.webp 的图片应引用为 /images/screenshot.webp。
图片尺寸
在图片 URL 之后追加 =WIDTHxHEIGHT（以空格分隔）来控制尺寸：
只设置其中一个维度，另一个会按比例缩放：
当你希望一列截图保持统一宽度，或需要将高分辨率图片缩小到合理展示尺寸时，这个功能非常有用。
说明文字
将图片包裹在 <Frame> 组件中，即可为其添加边框并在下方显示说明文字：
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame 会在图片周围绘制一个淡边框，并将说明文字放在下方。它不仅适用于图片，也适用于任何包裹在其中的内容。
浅色/深色模式
文档站点通常需要为每种配色方案准备不同的图片变体——白底 logo 在深色模式下会显得突兀。
srcDark 属性
最简单的方式。Jamdesk 会根据当前主题切换图片源：
<img
src="/_jd/images/logo-light.webp?v=mo97v0f0"
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=mo97v0f0" alt="Company logo" />
</picture><picture> 方案会遵循操作系统的配色方案设置。而 srcDark 属性则响应 Jamdesk 的主题切换，这通常才是文档场景下需要的行为。
支持的格式
| 格式 | 最适合 | 说明 |
|---|---|---|
| PNG | 截图、UI 截屏 | 无损画质，支持透明通道。文件较大。 |
| JPEG | 摄影照片 | 压缩效果好，不支持透明通道。 |
| SVG | 图标、示意图、logo | 矢量格式——可任意缩放而无画质损失。文件极小。 |
| GIF | 简单动画 | 体积容易迅速增大。超过数帧时建议考虑短 .mp4 循环。 |
| WebP | 通用 | 在相同画质下比 PNG 和 JPEG 更小。所有主流现代浏览器均支持。 |
对于大多数文档图片，WebP 能提供最佳的体积与画质比。如果需要透明通道，WebP 同样支持——不必再用 PNG。
最佳实践
Alt 文本有两个作用：屏幕阅读器会用它来提供无障碍支持；在图片加载失败时，它会作为占位文本显示。请描述图片实际展示的内容。
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
对于不传递信息的装饰性图片（背景图案、分隔线等），使用空 alt 文本：。
过大的图片会拖慢页面加载，尤其是在移动网络下。建议的目标体积：
- 截图/UI： PNG 或 WebP，小于 500KB
- 照片： JPEG 或 WebP，小于 200KB
- 图标和示意图： 尽量使用 SVG
Squoosh 和 TinyPNG 可以在视觉上几乎无损地压缩图片。提交截图前先跑一遍其中任意一个。
或者让 Jamdesk 在构建阶段自动处理。在 docs.json 中启用 自动 WebP 转换，提交的任何 PNG 或 JPG 都会在每次构建时被优化。
宽度忽大忽小的截图看起来很凌乱。选定一个标准的截屏宽度（1200px 通常比较合适），并在整套文档中统一使用。Jamdesk 会自动将图片缩放以适应内容区域，所以源图尺寸一致，渲染效果也会一致。
文件组织
将图片按与内容结构对应的子目录分组存放。这样随着文档规模增长，依然能方便查找：
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json
使用从项目根目录开始的完整路径来引用：
图片文件名中不要使用空格，改用连字符：api-response.webp，而不是 api response.webp。