# Embed videos

To put a video in an article, give your agent the link:

```
Embed this Loom walkthrough at the top of the onboarding article:
https://www.loom.com/share/abc123
```

The agent adds a `video` directive, and the article renders a responsive, playable embed.

## The video directive

In article source, a video looks like this:

```text
:::video{src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
:::
```

The `src` attribute is required and takes the ordinary URL you would share, not an embed code. Clayo works out the correct player at render time.

## Supported providers

**YouTube**

- `youtube.com/watch?v=VIDEO_ID`
- `youtu.be/VIDEO_ID`
- `youtube.com/embed/VIDEO_ID`
- `youtube.com/shorts/VIDEO_ID`

**Loom**

- `loom.com/share/VIDEO_ID`
- `loom.com/embed/VIDEO_ID`

**Vimeo**

- `vimeo.com/VIDEO_ID`
- `player.vimeo.com/video/VIDEO_ID`

Common variations are handled for you: `www.` and mobile `m.` prefixes are fine, and a URL without `https://` is accepted.

## How embeds behave

- The player is responsive and sized to the article column.
- Your original URL is what gets stored in the article, so switching a video later is a plain text edit.
- If a URL is not from a supported provider, the article still saves; the video block renders as a clear unsupported-video notice instead of a broken player, so a bad link is easy to spot in the preview.

:::callout{type="info"}
Only YouTube, Loom, and Vimeo are supported today. For anything else, link to the video instead of embedding it.
:::

## Where video works well in docs

A 60 second capture often explains a flow faster than five screenshots: onboarding walkthroughs, "what you'll build" intros, and anything involving drag-and-drop. Pair the video with written steps underneath it, because [search](/articles/search) and [AI answers](/articles/how-ai-answers-work) index your text, not your video.