Media & Embeds

Rich media makes documentation clearer and more engaging. Jamdesk supports images, video embeds, and iframes with automatic styling that includes rounded corners and consistent framing.

Images

Standard Markdown

The simplest way to add an image:

![Alt text describing the image](/images/screenshot.png)

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">

  ![Dashboard](/images/dashboard.png)

</Frame>

Your image here

Example of a framed image with caption

Light/Dark Mode Images

Show different images based on the user's color scheme:

<img
  src="/images/logo-light.svg"
  srcDark="/images/logo-dark.svg"
  alt="Company logo"
/>

Or use the HTML picture element:

<picture>
  <source srcset="/images/diagram-dark.png" media="(prefers-color-scheme: dark)" />
  <img src="/images/diagram-light.png" alt="Architecture diagram" />
</picture>

Video Embeds

Videos are automatically styled with rounded corners, a subtle border frame, and proper spacing. The video content clips to the rounded corners for a polished look.

YouTube

Embed YouTube videos using an iframe with the standard embed URL:

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  title="Video title"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
/>

To get the embed URL from YouTube, click Share → Embed and copy the src attribute from the provided iframe code.

Vimeo

Embed Vimeo videos similarly:

<iframe
  width="100%"
  height="360"
  src="https://player.vimeo.com/video/VIDEO_ID"
  title="Video title"
  allow="autoplay; fullscreen; 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
    style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%'}}
    src="https://www.youtube.com/embed/VIDEO_ID"
    title="Video title"
    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 */}
![API response showing user data in JSON format](/images/api-response.png)

{/* Avoid */}
![Screenshot](/images/api-response.png)

Large images slow down page loads. Aim for:

Screenshots: PNG, under 500KB
Photos: JPEG, under 200KB
Icons/diagrams: SVG when possible

Tools like Squoosh or TinyPNG can compress images without visible quality loss.

Keep screenshots at consistent widths (e.g., 1200px) for a polished look. Jamdesk automatically scales images to fit the content width.

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:

![Step 1](/images/getting-started/step-1.png)

What's Next?

Code Blocks

Syntax highlighting and code examples

Components

Interactive components for your docs