Images & Media
Add images, diagrams, and visual content to your documentation
Visuals make documentation clearer and more engaging. Jamdesk supports standard image formats and provides components for enhanced display.
Adding Images
Standard Markdown
The simplest way to add an image:
Place images in your /images directory and reference them with absolute paths.
With Captions
Use the Frame component to add a border and optional caption:
<Frame caption="Dashboard overview showing project statistics">
</Frame>Your image here
Image Best Practices
Alt text helps screen readers and appears when images fail to load. Describe what the image shows, not just "screenshot" or "image".
{/* Good */}
{/* Avoid */}
Keep screenshots at consistent widths (e.g., 1200px) for a polished look. Jamdesk automatically scales images to fit the content width.
Supported Formats
| Format | Best For | Notes |
|---|---|---|
| PNG | Screenshots, UI | Lossless, supports transparency |
| JPEG | Photos | Smaller files, no transparency |
| SVG | Icons, diagrams | Scales perfectly, tiny file size |
| GIF | Simple animations | Use sparingly, can be large |
| WebP | Modern alternative | Smaller than PNG/JPEG |
Light/Dark Mode Images
Show different images based on the user's color scheme:
<picture>
<source srcset="/images/diagram-dark.png" media="(prefers-color-scheme: dark)" />
<img src="/images/diagram-light.png" alt="Architecture diagram" />
</picture>Or use the dedicated dark mode image component:
<img
src="/images/logo-light.svg"
srcDark="/images/logo-dark.svg"
alt="Company logo"
/>Diagrams
For technical diagrams, consider:
- Draw.io / Excalidraw - Export as SVG for crisp rendering
- Mermaid - Code-based diagrams (coming soon)
- Screenshots - Annotated with arrows and callouts
SVG diagrams look sharp on all screen sizes and support dark mode with CSS.
Organization
Keep your images organized:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json
Reference them with the full path:
