---
title: Images
description: 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:
```markdown
```
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:
```markdown
```
Set only one dimension and the other scales proportionally:
```markdown
```
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 `` component to add a border and a caption below it:
```mdx
```
`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:
```mdx
```
The browser loads only the image that matches the current color scheme.
### The HTML `` element
If you need standard HTML that works outside Jamdesk too, use `` with a media query:
```mdx
```
The `` 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.
```markdown
{/* 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](https://squoosh.app) and [TinyPNG](https://tinypng.com) compress images without visible quality loss. Run screenshots through one of these before committing.
Or let Jamdesk handle it at build time. Enable [automatic WebP conversion](/builds/image-optimization) in your `docs.json` and any PNG or JPG you commit gets optimized on each build.
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:
```bash
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:
```markdown
```
Avoid spaces in image filenames. Use hyphens instead: `api-response.webp`, not `api response.webp`.
## What's Next?
Embed YouTube videos and Shorts
Local MP4 and WebM files
Vimeo, CodePen, Figma, and more
```
The browser loads only the image that matches the current color scheme.
### The HTML `