# Media Directives URL: /docs/reference/directives/media/ Section: directives Tags: reference, directives, media, video, audio, embed, youtube, vimeo, figure -------------------------------------------------------------------------------- Media Directives Media directives embed external content like videos, code playgrounds, and terminal recordings into your documentation. All embeds are privacy-respecting by default and meet WCAG 2.1 AA accessibility requirements. Quick Reference Directive Purpose Required Options {youtube} YouTube video :title: {vimeo} Vimeo video :title: {video} Self-hosted video :title: {figure} Image with caption :alt: {audio} Self-hosted audio :title: {gist} GitHub Gist — {codepen} CodePen embed :title: {codesandbox} CodeSandbox embed :title: {stackblitz} StackBlitz embed :title: {asciinema} Terminal recording :title: Video Embeds YouTube Embed YouTube videos with privacy-enhanced mode enabled by default (youtube-nocookie.com). Syntax: 1 2 3:::{youtube} VIDEO_ID :title: Video title for accessibility ::: Options: Option Default Description :title: (required) Accessible title for the iframe :privacy: true Use youtube-nocookie.com :start: — Start time in seconds :end: — End time in seconds :autoplay: false Auto-start video :muted: false Start muted (required with autoplay) :loop: false Loop video :controls: true Show player controls :aspect: 16/9 Aspect ratio (16/9, 4/3, 21/9) :class: — Additional CSS classes Example: Examples Basic embed: 1 2 3:::{youtube} dQw4w9WgXcQ :title: Rick Astley - Never Gonna Give You Up ::: With start time and custom aspect ratio: 1 2 3 4 5:::{youtube} dQw4w9WgXcQ :title: Rick Astley - Never Gonna Give You Up :start: 30 :aspect: 4/3 ::: Background video (autoplay, muted, looped, no controls): 1 2 3 4 5 6 7:::{youtube} dQw4w9WgXcQ :title: Background video :autoplay: true :muted: true :loop: true :controls: false ::: Vimeo Embed Vimeo videos with Do Not Track enabled by default. Syntax: 1 2 3:::{vimeo} VIDEO_ID :title: Video title for accessibility ::: Options: Option Default Description :title: (required) Accessible title for the iframe :dnt: true Enable Do Not Track mode :color: — Player accent color (hex without #) :background: false Background mode (no controls) :autoplay: false Auto-start video :muted: false Start muted :loop: false Loop video :aspect: 16/9 Aspect ratio :class: — Additional CSS classes Example: Examples Basic embed: 1 2 3:::{vimeo} 123456789 :title: My Vimeo Video ::: With custom color: 1 2 3 4:::{vimeo} 123456789 :title: My Vimeo Video :color: ff0000 ::: Self-Hosted Video Embed videos from your own server using HTML5 <video>. Syntax: 1 2 3:::{video} /path/to/video.mp4 :title: Video title for accessibility ::: Options: Option Default Description :title: (required) Accessible title :poster: — Poster image path :autoplay: false Auto-start video :muted: false Start muted :loop: false Loop video :controls: true Show player controls :preload: metadata Preload strategy (none, metadata, auto) :aspect: 16/9 Aspect ratio :class: — Additional CSS classes Supported formats: .mp4, .webm, .ogg, .mov Example: Examples Basic embed: 1 2 3:::{video} /assets/demo.mp4 :title: Product Demo ::: With poster and options: 1 2 3 4 5:::{video} /assets/demo.mp4 :title: Product Demo :poster: /assets/demo-poster.jpg :preload: auto ::: Figure (Images with Captions) Create semantic <figure> elements with optional captions, links, and alignment. Syntax: 1 2 3 4:::{figure} /path/to/image.png :alt: Descriptive alt text :caption: Optional caption text ::: Options: Option Default Description :alt: (required) Alt text (empty for decorative images) :caption: — Caption text below image :width: — Image width (80%, 500px) :height: — Image height :align: — Alignment (left, center, right) :link: — URL to link image to :target: — Link target (_blank for new tab) :loading: lazy Loading strategy (lazy, eager) :class: — Additional CSS classes Supported formats: .png, .jpg, .jpeg, .gif, .webp, .svg, .avif Example: Examples Basic figure with alt text: 1 2 3:::{figure} /images/architecture.png :alt: System architecture diagram showing component relationships ::: With caption and alignment: 1 2 3 4 5 6:::{figure} /images/screenshot.png :alt: Application dashboard :caption: The main dashboard showing key metrics :align: center :width: 80% ::: Linked image opening in new tab: 1 2 3 4 5:::{figure} /images/diagram.png :alt: Workflow diagram :link: https://example.com/full-diagram :target: _blank ::: Decorative image (empty alt): 1 2 3:::{figure} /images/decorative-border.png :alt: ::: Audio Embed self-hosted audio files using HTML5 <audio>. Syntax: 1 2 3:::{audio} /path/to/audio.mp3 :title: Audio title for accessibility ::: Options: Option Default Description :title: (required) Accessible title :autoplay: false Auto-start audio :loop: false Loop audio :controls: true Show player controls :preload: metadata Preload strategy :class: — Additional CSS classes Supported formats: .mp3, .ogg, .wav, .m4a Example: Examples Basic audio: 1 2 3:::{audio} /assets/podcast-episode-1.mp3 :title: Episode 1 - Getting Started ::: Background audio: 1 2 3 4 5 6:::{audio} /assets/ambience.mp3 :title: Ambient sound :autoplay: true :loop: true :controls: false ::: Code Playground Embeds GitHub Gist Embed GitHub Gists with optional file selection. Syntax: 1 2 3:::{gist} USERNAME/GIST_ID :file: optional-filename.py ::: Options: Option Default Description :file: — Specific file from multi-file gist Example: Examples Basic gist: 1 2:::{gist} octocat/12345678901234567890123456789012 ::: Specific file: 1 2 3:::{gist} octocat/12345678901234567890123456789012 :file: example.py ::: CodePen Embed CodePen pens. Syntax: 1 2 3:::{codepen} USERNAME/PEN_ID :title: Pen title for accessibility ::: Options: Option Default Description :title: (required) Accessible title :default-tab: result Default tab (html, css, js, result) :theme: dark Theme (dark, light) :height: 400 Embed height in pixels :class: — Additional CSS classes Example: Examples Basic embed: 1 2 3:::{codepen} chriscoyier/KBQqza :title: CSS Grid Layout Example ::: With HTML tab visible: 1 2 3 4 5:::{codepen} chriscoyier/KBQqza :title: CSS Grid Layout Example :default-tab: html :height: 500 ::: CodeSandbox Embed CodeSandbox projects. Syntax: 1 2 3:::{codesandbox} SANDBOX_ID :title: Sandbox title for accessibility ::: Options: Option Default Description :title: (required) Accessible title :module: — Initial file to open (/src/App.js) :view: split View mode (editor, preview, split) :height: 500 Embed height in pixels :class: — Additional CSS classes Example: Examples Basic embed: 1 2 3:::{codesandbox} new-react-app :title: React Starter ::: With specific file: 1 2 3 4 5:::{codesandbox} new-react-app :title: React Starter :module: /src/App.js :view: editor ::: StackBlitz Embed StackBlitz projects. Syntax: 1 2 3:::{stackblitz} PROJECT_ID :title: Project title for accessibility ::: Options: Option Default Description :title: (required) Accessible title :file: — Initial file to open :view: both View mode (editor, preview, both) :height: 500 Embed height in pixels :class: — Additional CSS classes Example: Examples Basic embed: 1 2 3:::{stackblitz} angular-quickstart :title: Angular Quickstart ::: With specific file: 1 2 3 4 5:::{stackblitz} angular-quickstart :title: Angular Quickstart :file: src/app.component.ts :view: editor ::: Terminal Recordings Asciinema Embed terminal recordings from asciinema.org. Syntax: 1 2 3:::{asciinema} RECORDING_ID :title: Recording title for accessibility ::: Options: Option Default Description :title: (required) Accessible ARIA label :cols: — Terminal width in columns :rows: — Terminal height in rows :speed: 1.0 Playback speed multiplier :autoplay: false Auto-start playback :loop: false Loop recording :preload: false Preload recording data :class: — Additional CSS classes Example: Examples Basic embed: 1 2 3:::{asciinema} 590029 :title: Installing Bengal with pip ::: With custom size and speed: 1 2 3 4 5 6 7:::{asciinema} 590029 :title: Installing Bengal with pip :cols: 120 :rows: 30 :speed: 2.0 :autoplay: true ::: Accessibility Requirements All media embeds follow WCAG 2.1 AA guidelines: Required titles: All iframes require a :title: option for screen readers Alt text: Figures require :alt: text (use empty string for decorative images) Fallback content: All embeds include <noscript> fallbacks with direct links Keyboard navigation: Video/audio players support keyboard controls ARIA labels: Terminal recordings use role="img" and aria-label Privacy Features Media embeds are privacy-respecting by default: YouTube: Uses youtube-nocookie.com (disable with :privacy: false) Vimeo: Enables Do Not Track (disable with :dnt: false) No third-party tracking: Self-hosted options available for video, audio, figures Security All media directives validate inputs to prevent: XSS attacks: ID/URL validation rejects malicious input Path traversal: Local paths cannot escape content directory Iframe sandboxing: External embeds use restricted sandbox attributes Responsive Design All embeds use CSS aspect-ratio for fluid responsive layouts: 1 2 3 4.video-embed iframe, .video-embed video { aspect-ratio: var(--video-aspect, 16/9); } Override the aspect ratio with the :aspect: option or custom CSS classes. Related Layout Directives - Cards, tabs, grids Interactive Directives - Code tabs, data tables Hugo Migration - Migrating from Hugo shortcodes -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1266 - Reading Time: 6 minutes