---
title: "Videos"
guide-section: "Site Content"
bread-crumbs: false
tags: [Content, Multimedia]
versions: ">=0.3"
---

# Videos

Videos can make tutorials, demos, and explainers far more effective than screenshots alone. Great
Docs supports YouTube, Vimeo, and local video files with responsive layouts, lazy loading, and
accessibility features built in.

## YouTube

Use the following syntax to embed a YouTube video. You can use the regular watch URL, the short URL,
or the embed URL (all three work):

```{shortcodes="false"}
{{< video https://www.youtube.com/watch?v=wo9vZccmqwc >}}

{{< video https://youtu.be/wo9vZccmqwc >}}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}
```

All three produce the same result. The video is responsive by default and it scales to fill the
available width while maintaining a 16:9 aspect ratio.

Here's a live example:

{{< video https://www.youtube.com/watch?v=d8-Jyh-NaMw >}}

::: {.callout-tip}
## YouTube Controls

YouTube embeds use the standard YouTube player, giving visitors full access to native controls
including ad skipping, captions, playback speed, and quality settings.
:::

### Start Time

To start playback at a specific point, use the `start` option (in seconds):

```{shortcodes="false"}
{{< video https://youtu.be/wo9vZccmqwc start="116" >}}
```

### Title and Accessibility

Add a `title` for the iframe and an `aria-label` for screen readers:

```{shortcodes="false"}
{{< video https://www.youtube.com/embed/wo9vZccmqwc
    title="What is the CERN?"
    aria-label="Video tour of CERN particle physics laboratory"
>}}
```

## Vimeo

Vimeo videos work the same way:

```{shortcodes="false"}
{{< video https://vimeo.com/548291297 >}}
```

Vimeo embeds are lazy-loaded automatically: the iframe content is deferred until the video scrolls
near the viewport.

## Local Video Files

To embed a video file stored alongside your documentation (e.g., a short screen recording), place
the file in your project and reference it directly:

```{shortcodes="false"}
{{< video demo.mp4 >}}
```

Local videos are rendered as HTML5 `<video>` elements. To host them alongside your `.qmd` files,
place them in the `assets/` directory:

```
user_guide/
├── 05-walkthrough.qmd
└── assets/
    └── demo.mp4
```

Then reference from the `.qmd` file:

```{shortcodes="false"}
{{< video assets/demo.mp4 >}}
```

::: {.callout-note}
Keep video files small. Git repositories aren't ideal for large binary files. For longer recordings,
consider uploading to YouTube or Vimeo and embedding from there.
:::

## Aspect Ratio

The default aspect ratio is 16:9. You can change it to one of the standard Bootstrap ratios:

```{shortcodes="false"}
{{< video https://youtu.be/wo9vZccmqwc aspect-ratio="4x3" >}}
```

Available ratios: `1x1`, `4x3`, `16x9` (default), and `21x9`.

## Fixed Dimensions

To disable responsive sizing and set explicit pixel dimensions:

```{shortcodes="false"}
{{< video https://youtu.be/wo9vZccmqwc width="400" height="225" >}}
```

## Cross-Referencing Videos

To create a numbered, cross-referenceable video (like a figure), wrap it in a fenced div:

```{shortcodes="false"}
::: {#fig-demo}

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

A short tour of the CERN facility.

:::

See @fig-demo for the full walkthrough.
```

This assigns the video a figure number and caption, and `@fig-demo` creates a clickable
cross-reference elsewhere on the page.

## Loom

Loom videos aren't recognized by the video syntax directly. Instead, use the Loom embed URL in a raw
HTML `<iframe>`:

```html
<div class="quarto-video ratio ratio-16x9">
<iframe
  src="https://www.loom.com/embed/YOUR_VIDEO_ID"
  frameborder="0"
  allowfullscreen>
</iframe>
</div>
```

Replace `YOUR_VIDEO_ID` with the ID from your Loom share link (e.g., if the share link is
`https://www.loom.com/share/abc123`, the ID is `abc123`). The `quarto-video ratio ratio-16x9`
classes give it the same responsive container as other videos, and Great Docs will lazy-load the
iframe automatically.

## Tips

- **Ads**: YouTube may show ads on monetized videos, even in embeds. To guarantee an ad-free
experience, upload to a channel you control with monetization disabled.
- **Privacy**: Consider using `youtube-nocookie.com` embed URLs (e.g.,
`https://www.youtube-nocookie.com/embed/VIDEO_ID`) to reduce tracking.
- **Multiple videos**: The thumbnail placeholder optimization means pages with many YouTube embeds
still load quickly (only the thumbnails are fetched initially).

## Next Steps

Embedded videos bring tutorials, demos, and walkthroughs to life without leaving the documentation
site. Great Docs lazy-loads all video embeds for fast page loads, regardless of how many videos
appear on a page.

- [Diagrams](diagrams.qmd) covers Mermaid diagrams for visualizing architecture and workflows
- [Authoring QMD Files](authoring-qmd-files.qmd) covers other rich content like callouts, tabsets,
and code blocks
- [Theming & Appearance](theming.qmd) explains how video containers adapt to your site's styling
