Images
Add images to your docs with markdown syntax, dimension controls, captions, and light/dark mode support.
Jamdesk renders images with rounded corners and consistent spacing. Drop files into your /images directory and reference them with standard markdown.
Standard Markdown
Use the familiar  syntax:
Paths start from your project root. An image at your-docs/images/screenshot.webp is referenced as /images/screenshot.webp.
Image Dimensions
Append =WIDTHxHEIGHT after the image URL (separated by a space) to control sizing:
Set only one dimension and the other scales proportionally:
This is useful when you want a consistent column of screenshots at the same width, or need to shrink a high-resolution image to a reasonable display size.
Captions
Wrap an image in the <Frame> component to add a border and a caption below it:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame draws a subtle border around the image and places the caption text underneath. It works with any content inside it, not just images.
Light/Dark Mode
Docs sites often need different image variants for each color scheme -- a logo on a white background looks wrong in dark mode.
The srcDark attribute
The simplest approach. Jamdesk swaps the image source based on the active theme:
<img
src="/_jd/images/logo-light.webp?v=mnrsgrr6"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>The browser loads only the image that matches the current color scheme.
The HTML <picture> element
If you need standard HTML that works outside Jamdesk too, use <picture> with a media query:
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mnrsgrr6" alt="Company logo" />
</picture>The <picture> approach respects the operating system's color scheme setting. The srcDark attribute responds to Jamdesk's theme toggle instead, which is usually what you want for docs.
Supported Formats
| Format | Best for | Notes |
|---|---|---|
| PNG | Screenshots, UI captures | Lossless quality, supports transparency. Larger files. |
| JPEG | Photographs | Good compression, no transparency support. |
| SVG | Icons, diagrams, logos | Vector format -- scales to any size with zero quality loss. Tiny file size. |
| GIF | Simple animations | Can get large fast. Consider short .mp4 loops for anything over a few frames. |
| WebP | General purpose | Smaller than PNG and JPEG at comparable quality. Works in all modern browsers. |
WebP gives you the best size-to-quality ratio for most documentation images. If you need transparency, WebP handles that too -- no need for PNG.
Best Practices
Alt text serves two purposes: screen readers use it for accessibility, and it shows up as a placeholder when the image fails to load. Describe what the image actually shows.
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
For decorative images that don't add information (background patterns, dividers), use empty alt text: .
Heavy images slow page loads, especially on mobile connections. Target sizes:
- Screenshots/UI: PNG or WebP, under 500KB
- Photos: JPEG or WebP, under 200KB
- Icons and diagrams: SVG whenever possible
Squoosh and TinyPNG compress images without visible quality loss. Run screenshots through one of these before committing.
Screenshots that jump between different widths look messy. Pick a standard capture width (1200px works well) and use it across your docs. Jamdesk scales images to fit the content area automatically, so consistent source dimensions produce consistent rendered results.
File Organization
Group images into subdirectories that mirror your content structure. This keeps things findable as your docs grow:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json
Reference them with the full path from your project root:
Avoid spaces in image filenames. Use hyphens instead: api-response.webp, not api response.webp.