Embeds — Loom, YouTube, Figma, more

Embedded content adds bandwidth, blocks scripts in some browsers, and slows page load. It's worth using when it genuinely beats a screenshot or a code block — and worth skipping when it doesn't.

When an embed is worth it

A 30-second walkthrough of a UI flow. Loom or a screen recording is faster than 600 words.
A live, interactive demo. Figma prototype, CodeSandbox, Stackblitz.
A conference talk or recorded webinar. A YouTube embed beats writing it up from scratch.

When to skip the embed

Anything that's a single screenshot. Just embed the screenshot.
A talk where the slides convey the content. Link to the slides instead.
Marketing-heavy videos. Docs aren't a sales surface; visitors here have already bought in.
**Anything you'd embed because the page "needs more visuals". The page might just be too long.

Loom

Best for: short walkthroughs of UI behavior. Sweet spot is 30s–2min videos.

<iframe
  src="https://www.loom.com/embed/<id>"
  width="100%"
  height="450"
  frameBorder="0"
  allowFullScreen
/>

Make the videos short. A four-minute Loom in the docs is read by no one.

YouTube

Best for: existing recorded content (talks, tutorials).

<iframe
  src="https://www.youtube.com/embed/<id>"
  width="100%"
  height="450"
  frameBorder="0"
  allowFullScreen
/>

Use ?rel=0 in the embed URL to disable "related videos" suggestions; otherwise YouTube cross-promotes whatever they want next to your content.

Figma

Best for: design system pages, component reference, mocks of upcoming features.

<iframe
  src="https://www.figma.com/embed?embed_host=docsio&url=<figma-public-url>"
  width="100%"
  height="500"
  frameBorder="0"
/>

Figma's free tier allows public embed with view-only access. For private files, use a screenshot.

CodeSandbox / StackBlitz

Best for: SDK pages where the visitor benefits from running real code.

<iframe
  src="https://codesandbox.io/embed/<sandbox-id>?fontsize=14&hidenavigation=1&theme=dark"
  width="100%"
  height="500"
  frameBorder="0"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; microphone"
  sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
/>

Use theme=dark to match the docs in dark mode. The iframe takes ~3 seconds to boot — heavy but worth it for examples that "just work" without the reader leaving the page.

What to put right next to embeds

Always pair an embed with a one-line description and a link to the source:

Quick walkthrough of setting up GitHub Sync — full instructions: GitHub Sync overview.

[Embed]

Reasons:

AI assistants can't watch your videos. The text gives them something to cite.
Visitors with bandwidth issues can use the link instead.
The embed might break in 18 months. The link to a real page won't.

Auto-playing videos. Always require a click. No exceptions.
Embeds in the first paragraph of a page. Lead with text. The embed is a supplement, not the lede.
More than two embeds per page. Page weight stacks fast.
Tweets/X posts as content. They get deleted, the link breaks, the page rots.