Video

A video shows a poster and a play button, and loads the provider's player only when the reader asks for it. Until then the page makes no request to the provider or its thumbnail CDN. The frame keeps a 16

ratio, so nothing shifts when the player replaces the poster. Captions and a transcript sit under the player as static markup, so they remain readable when JavaScript or the player fails.

Syntax

::video{src="https://www.youtube.com/watch?v=aqz-KE-bpKQ" title="Big Buck Bunny" poster="/media/big-buck-bunny.jpg"}

A transcript is the body of a container directive:

:::video{src="https://www.youtube.com/watch?v=aqz-KE-bpKQ" title="Big Buck Bunny" captions="/media/big-buck-bunny.en.vtt" captions_label="English captions" transcript_label="Transcript"}
The bunny wakes up in a forest and meets the other animals.
:::

Options

Name	Type	Required	What it does
src	https URL	yes	The video page. A YouTube watch, short, or share link becomes the privacy-friendly youtube-nocookie.com embed.
title	string	yes	The player's accessible name. Without it the component renders a message instead of the video.
poster	local path	no	The image shown before the reader plays. It must be root-relative, so it comes from this site. A remote poster is rejected and a video without one shows a plain surface; the provider thumbnail is never fetched automatically.
captions	https URL or local path	no	A WebVTT captions file. It renders as a link, not a request.
captions_label	string	with captions	The visible and accessible label of the captions link: "English captions", not "here".
transcript	https URL or local path	no	A linked transcript, shown when the directive has no body.
transcript_label	string	with transcript or a body	The label of the transcript disclosure or link. Without it the body is shown plainly and a transcript URL is ignored.

Only https addresses are played, and only safe https or root-relative addresses become captions or transcript links. An unsafe src, captions, or transcript value is rejected, and an unsafe poster is ignored.

Example

Notes

• Give a title that names the content, not the provider: "Big Buck Bunny", not "YouTube video".
• Author the poster locally. A remote image would defeat the consent gate before the reader clicks.
• Pair every captions file or transcript link with a label that says what it is. The component adds no translated text of its own here, so the label reads correctly in the page's language.
• The provider link stays under the box before and after activation, so a failed or blocked player leaves a way through.
• For a link to a video with no player, use an ordinary Markdown link; it is lighter still.