Media & Embeds
Add images, YouTube videos, and iframes to your docs. Includes dimension syntax, dark mode images, and Frame captions.
Jamdesk styles images, video embeds, and iframes automatically with rounded corners and consistent framing.
Images
Standard Markdown
The simplest way to add an image:
Place images in your /images directory and reference them with absolute paths.
Image Dimensions
Control image size by appending dimensions after the URL:
The syntax is =WIDTHxHEIGHT with a space before the equals sign.
Width only (height auto-scales):
Height only (width auto-scales):
With Captions
Use the Frame component to add a border and optional caption:
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Light/Dark Mode Images
Show different images based on the user's color scheme:
<img
src="/_jd/images/logo-light.webp?v=mml1g89b"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>Or use the HTML picture element:
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mml1g89b" alt="Company logo" />
</picture>Video Embeds
Videos get the same rounded-corner styling as images.
YouTube
The simplest way to embed YouTube videos is with the <YouTube> component:
<YouTube id="dQw4w9WgXcQ" />Just pass the video ID from the YouTube URL (the part after v=). The component automatically:
- Lazy-loads the video player (only loads when clicked)
- Disables related videos at the end
- Applies consistent rounded styling
Props
| Prop | Type | Description |
|---|---|---|
id | string | YouTube video ID (required) |
title | string | Accessibility label for the play button |
start | number | Start time in seconds |
Start at a specific time
Use the start prop to begin playback at a specific point:
<YouTube id="dQw4w9WgXcQ" start={60} />This starts the video at 1 minute (60 seconds).
To find the video ID, look at the YouTube URL: youtube.com/watch?v=VIDEO_ID or youtu.be/VIDEO_ID
Using iframes directly
For more control, you can embed YouTube videos using an iframe:
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/VIDEO_ID"
title="YouTube video player"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/>The <YouTube> component is recommended over raw iframes because it lazy-loads the player, improving page load performance.
Vimeo
Embed Vimeo videos similarly:
<iframe
className="w-full aspect-video rounded-xl"
src="https://player.vimeo.com/video/VIDEO_ID"
title="YouTube video player"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/>Responsive Videos
For fully responsive videos that maintain aspect ratio:
<div style={{position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden'}}>
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/VIDEO_ID"
title="YouTube video player"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/>
</div>The 56.25% padding creates a 16:9 aspect ratio. Use 75% for 4:3.
Iframes
Any iframe content is automatically styled with:
- Rounded corners on both the frame and content
- Subtle border that adapts to light/dark mode
- Consistent spacing above and below
Embedding External Content
<iframe
src="https://example.com/embed"
width="100%"
height="400"
title="Description of embedded content"
/>Common Embeds
<iframe
height="400"
style={{width: '100%'}}
src="https://codepen.io/USERNAME/embed/PEN_ID?default-tab=result"
title="CodePen Embed"
allowFullScreen
/><iframe
src="https://codesandbox.io/embed/SANDBOX_ID?fontsize=14&theme=dark"
style={{width: '100%', height: '500px', border: 0, borderRadius: '4px', overflow: 'hidden'}}
title="CodeSandbox"
allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
/><iframe
style={{border: '1px solid rgba(0, 0, 0, 0.1)'}}
width="100%"
height="450"
src="https://www.figma.com/embed?embed_host=share&url=FIGMA_URL"
allowFullScreen
/><iframe
src="https://www.loom.com/embed/VIDEO_ID"
width="100%"
height="400"
allowFullScreen
/>Styling Details
All iframes receive automatic styling for a consistent look:
| Property | Value | Description |
|---|---|---|
| Border radius | 0.5rem | Rounded corners on content |
| Frame width | 8px | Visual padding around content |
| Border | 1px | Subtle border in theme color |
| Spacing | 1rem + 9px | Margin above and below |
The styling adapts to your theme's color scheme, using --color-bg-secondary for the frame and --color-border for the border line.
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). Jamdesk scales images to fit the content width automatically.
Supported Image 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 |
File Organization
Keep your media 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:
