Add shared Video component for YouTube embeds (#5136)

Replaces hand-rolled YouTube iframes with a click-to-play facade that
defers loading until clicked, uses the youtube-nocookie.com domain, and
enforces a consistent centered/max-width appearance. Migrates the 5
single-video embeds; playlist embeds and the local mp4 in
design-patterns/approval.mdx are left as-is.

Author: Duncanma

docs/encyclopedia/activities/activities.mdx

@@ -17,26 +17,17 @@ tags:
   - Durable Execution
 ---
 
+import { Video } from '@site/src/components';
+
 This guide provides a comprehensive overview of Temporal Activities including
 [Activity Definition](/activity-definition), [Activity Type](/activity-definition#activity-type),
 [Activity Execution](/activity-execution), [Local Activity](/local-activity), and [Standalone Activity](/standalone-activity).
 
 :::tip
 
-Watch [What is an Activity in Temporal?](https://www.youtube.com/watch?v=rtWrzjnKlSQ) for a short overview.
+Watch a short overview of what an Activity is in Temporal:
 
-<div style={{ display: 'flex', justifyContent: 'center' }}>
-  <iframe
-    width="560"
-    height="315"
-    src="https://www.youtube.com/embed/rtWrzjnKlSQ"
-    title="What is an Activity in Temporal?"
-    frameBorder="0"
-    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-    referrerPolicy="strict-origin-when-cross-origin"
-    allowFullScreen
-  ></iframe>
-</div>
+<Video videoId="rtWrzjnKlSQ" title="What is an Activity in Temporal?" />
 
 :::
 

docs/encyclopedia/temporal.mdx

@@ -16,7 +16,7 @@ tags:
   - Concepts
 ---
 
-import { CaptionedImage, QuickstartCards } from '@site/src/components';
+import { CaptionedImage, QuickstartCards, Video } from '@site/src/components';
 
 Temporal is a scalable and reliable runtime for durable function executions called [Temporal Workflow Executions](/workflow-execution).
 
@@ -41,20 +41,9 @@ If a failure occurs, the Workflow Execution can resume from the last recorded ev
 
 :::tip
 
-Watch [What is the Temporal Platform?](https://www.youtube.com/watch?v=EwweiH2rd7M) for a short overview.
-
-<div style={{ display: 'flex', justifyContent: 'center' }}>
-  <iframe
-    width="560"
-    height="315"
-    src="https://www.youtube.com/embed/EwweiH2rd7M"
-    title="What is the Temporal Platform?"
-    frameBorder="0"
-    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-    referrerPolicy="strict-origin-when-cross-origin"
-    allowFullScreen
-  ></iframe>
-</div>
+Watch a short overview of the Temporal Platform:
+
+<Video videoId="EwweiH2rd7M" title="What is the Temporal Platform?" />
 
 :::
 

docs/encyclopedia/workflow/workflow-overview.mdx

@@ -13,6 +13,8 @@ tags:
   - Workflows
 ---
 
+import { Video } from '@site/src/components';
+
 This guide provides a comprehensive overview of Temporal Workflows and covers the following:
 
 - [Workflow Definition](/workflow-definition)
@@ -25,20 +27,9 @@ This guide provides a comprehensive overview of Temporal Workflows and covers th
 
 :::tip
 
-Watch [What Is a Workflow in Temporal?](https://www.youtube.com/watch?v=zLjhNrOKphE) for a short overview.
-
-<div style={{ display: 'flex', justifyContent: 'center' }}>
-  <iframe
-    width="560"
-    height="315"
-    src="https://www.youtube.com/embed/zLjhNrOKphE"
-    title="What Is a Workflow in Temporal?"
-    frameBorder="0"
-    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-    referrerPolicy="strict-origin-when-cross-origin"
-    allowFullScreen
-  ></iframe>
-</div>
+Watch a short overview of what a Workflow is in Temporal:
+
+<Video videoId="zLjhNrOKphE" title="What Is a Workflow in Temporal?" />
 
 :::
 

docs/evaluate/why-temporal.mdx

@@ -13,6 +13,8 @@ tags:
   - Durable Execution
 ---
 
+import { Video } from '@site/src/components';
+
 # Why Temporal?
 
 Temporal solves many problems that developers face while building distributed applications.
@@ -27,14 +29,7 @@ You can check out a list of [use cases for Temporal](/evaluate/use-cases-design-
 :::tip See Temporal in action
 Watch the following video to see how Temporal ensures an order-fulfillment system can recover from various failures, from process crashes to unreachable APIs.
 
-<div style={{ display: 'flex', justifyContent: 'center' }}>
-    <iframe width="560" height="315"
-        src="https://www.youtube.com/embed/dNVmRfWsNkM?si=cfwAJgr2zaoro97P"
-        title="YouTube video player"
-        frameBorder="0"
-        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-        referrerPolicy="strict-origin-when-cross-origin" allowFullScreen></iframe>
-</div>
+<Video videoId="dNVmRfWsNkM" title="Recovering an order-fulfillment system from failures with Temporal" />
 :::
 
 ## Reliable execution

docs/production-deployment/worker-deployments/worker-versioning/index.mdx

@@ -16,6 +16,8 @@ tags:
   - Durable Execution
 ---
 
+import { Video } from '@site/src/components';
+
 Worker Versioning is a Temporal feature that allows you to confidently deploy new changes to the Workflows running on
 your Workers without breaking them. Temporal enables this by helping you manage different builds or versions, formally
 called [Worker Deployment Versions](/worker-versioning#deployment-versions).
@@ -40,18 +42,7 @@ To use Workflow Pinning, we recommend using [rainbow deployments](#deployment-sy
 
 Watch this Temporal Replay 2025 talk to learn more about Worker Versioning and see a demo.
 
-<div style={{ display: 'flex', justifyContent: 'center' }}>
-  <iframe
-    width="560"
-    height="315"
-    src="https://www.youtube.com/embed/rm4BlD9WXqc"
-    title="YouTube video player"
-    frameBorder="0"
-    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-    referrerPolicy="strict-origin-when-cross-origin"
-    allowFullScreen
-  ></iframe>
-</div>
+<Video videoId="rm4BlD9WXqc" title="Worker Versioning: a Temporal Replay 2025 talk and demo" />
 
 :::
 

readme/COMPONENTS.md

@@ -20,6 +20,7 @@ Whether you’re using core components or experimenting with new ones, this guid
 - [Using Components in MDX Source Files](#using-components-in-mdx-source-files)
 - [Using IntegrationsGrid](#using-integrationsgrid)
 - [Using CaptionedImage](#using-captionedimage)
+- [Using Video](#using-video)
 - [Using DocsTable](#using-docstable)
 - [Using RelatedRead](#using-relatedread)
 - [Using ToolTipTerm](#using-tooltipterm)
@@ -251,6 +252,26 @@ One click will zoom out, another will zoom back.
 Most rendering will allow readers to pull the image around to view all parts of the image. 
 On non-mobile systems, cursors will change to interactive elements when hovered above zoomable items to indicate interaction.
 
+## Using Video
+
+Video embeds a YouTube video behind a click-to-play facade. It enforces a consistent, centered, width-constrained appearance across the site, always points at the `youtube-nocookie.com` embed domain, and defers loading the real iframe (and YouTube's tracking scripts) until the reader clicks the thumbnail.
+
+Usage:
+
+```
+<Video videoId="EwweiH2rd7M" title="What is the Temporal Platform?" />
+```
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `videoId` | `string` | Yes | The YouTube video ID (the `v=` value from a `youtube.com/watch` URL). |
+| `title` | `string` | Yes | A descriptive title. Used as the iframe's accessible title, the play button's `aria-label`, and the "Watch" link generated for the LLM Markdown pipeline (see [MARKDOWN_PIPELINE.md](./MARKDOWN_PIPELINE.md)). |
+| `maxWidth` | `string` | No | Escape hatch to override the default width for a documented one-off exception. Most pages should omit this and use the standard width. |
+
+Because `Video` generates the "Watch: {title}" link for the LLM Markdown feed automatically, you no longer need to hand-write a separate `Watch [Title](url)` sentence purely for that purpose. You can still add a short lead-in sentence for human readers (for example, "Watch a short overview:") above the component.
+
+**Not yet supported:** embedding a YouTube playlist (`videoseries?list=...`). The two pages that still embed a playlist ([`docs/develop/python/workflows/versioning.mdx`](../docs/develop/python/workflows/versioning.mdx) and [`docs/develop/dotnet/workflows/versioning.mdx`](../docs/develop/dotnet/workflows/versioning.mdx)) continue to use a raw `<iframe>` until playlist support is added.
+
 ## Using DocsTable
 
 In certain rare instances, standard Markdown tables won't work for our needs.

readme/COMPONENT_REGISTRY.md

@@ -2,25 +2,26 @@
 
 Generated by `scripts/audit-components.mjs`. Run to update.
 
-**Coverage: 40/48 (83%)**
+**Coverage: 41/49 (84%)**
 
 | Component | File Count | Strategy | Covered |
 |-----------|------------|----------|---------|
-| `TabItem` | 82 | `tabitem` | ✅ |
-| `Tabs` | 81 | `tabs` | ✅ |
-| `ReleaseNoteHeader` | 71 | `release-note-header` | ✅ |
+| `TabItem` | 84 | `tabitem` | ✅ |
+| `Tabs` | 83 | `tabs` | ✅ |
+| `ReleaseNoteHeader` | 76 | `release-note-header` | ✅ |
 | `NoZoom` | 60 | `UNKNOWN` | ❌ |
 | `RelatedReadContainer` | 23 | `related-read-container` | ✅ |
 | `RelatedReadItem` | 20 | `related-read-item` | ✅ |
-| `SetupSteps` | 14 | `setup-steps` | ✅ |
-| `SetupStep` | 14 | `setup-step` | ✅ |
-| `CodeSnippet` | 14 | `code-snippet` | ✅ |
+| `SetupSteps` | 20 | `setup-steps` | ✅ |
+| `SetupStep` | 20 | `setup-step` | ✅ |
+| `CodeSnippet` | 20 | `code-snippet` | ✅ |
 | `PatternCards` | 13 | `cards` | ✅ |
-| `SdkTabs` | 9 | `sdk-tabs` | ✅ |
-| `CallToAction` | 8 | `call-to-action` | ✅ |
+| `SdkTabs` | 12 | `sdk-tabs` | ✅ |
+| `CallToAction` | 9 | `call-to-action` | ✅ |
 | `CaptionedImage` | 7 | `captioned-image` | ✅ |
 | `ViewSourceCodeNotice` | 6 | `view-source-code-notice` | ✅ |
 | `IntegrationsGrid` | 6 | `integrations-grid` | ✅ |
+| `Video` | 5 | `video` | ✅ |
 | `CodeToCommandsDemo` | 5 | `strip-block` | ✅ |
 | `CommandsToEventsDemo` | 5 | `strip-block` | ✅ |
 | `HistoryReplayDemo` | 5 | `strip-block` | ✅ |

scripts/mdx-to-md.mjs

@@ -61,6 +61,7 @@ export const COMPONENT_REGISTRY = {
   SdkGuideLinks: "sdk-guide-links",
   CaptionedImage: "captioned-image",
   EnlargeImage: "captioned-image",
+  Video: "video",
   CodeSnippet: "code-snippet",
   SdkTabs: "sdk-tabs",
   ToolTipTerm: "tooltip-term",
@@ -953,6 +954,21 @@ export function transformMdx(mdxContent, options = {}) {
           i = embedEnd;
           continue;
         }
+        // <Video videoId="..." title="..." /> inside a tip → Watch link, same
+        // as the Video strategy used outside admonitions.
+        if (/^\s*<Video\b/.test(line)) {
+          let tag = line;
+          while (!/\/>/.test(tag) && i + 1 < lines.length) {
+            i++;
+            tag += " " + lines[i].trim();
+          }
+          const videoId = extractProp(tag, "videoId");
+          const title = extractProp(tag, "title");
+          if (videoId && title) {
+            admonitionLines.push(`[Watch: ${title}](https://www.youtube.com/watch?v=${videoId})`);
+          }
+          continue;
+        }
         admonitionLines.push(line);
       }
       continue;
@@ -1209,6 +1225,23 @@ export function transformMdx(mdxContent, options = {}) {
       continue;
     }
 
+    // --- Video (self-closing, may span lines) ---
+    //     <Video videoId="..." title="..." /> → [Watch: Title](https://www.youtube.com/watch?v=ID)
+    if (state === State.NORMAL && /^\s*<Video\b/.test(line)) {
+      let tag = line;
+      while (!/\/>/.test(tag) && i + 1 < lines.length) {
+        i++;
+        tag += " " + lines[i].trim();
+      }
+      const videoId = extractProp(tag, "videoId");
+      const title = extractProp(tag, "title");
+      if (videoId && title) {
+        outputLines.push(`[Watch: ${title}](https://www.youtube.com/watch?v=${videoId})`);
+        outputLines.push("");
+      }
+      continue;
+    }
+
     // --- JsonTable (self-closing data component) ---
     if (state === State.NORMAL && /^\s*<JsonTable\b/.test(line)) {
       let tag = line;

src/components/elements/Video/Video.module.css

@@ -0,0 +1,88 @@
+.container {
+  --video-max-width: 750px;
+  max-width: var(--video-max-width);
+  width: 100%;
+  margin: 2rem auto;
+}
+
+.aspectBox {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  border-radius: 8px;
+  overflow: hidden;
+  background: #000;
+}
+
+.facade {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  padding: 0;
+  margin: 0;
+  border: 0;
+  background: none;
+  cursor: pointer;
+  display: block;
+}
+
+.thumbnail {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+.playButton {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 68px;
+  height: 48px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.7);
+  border-radius: 14px;
+  transition: background-color 0.15s ease, transform 0.15s ease;
+}
+
+.facade:hover .playButton {
+  background: rgba(210, 30, 30, 0.85);
+  transform: translate(-50%, -50%) scale(1.05);
+}
+
+.facade:focus-visible {
+  outline: 3px solid var(--ifm-color-primary);
+  outline-offset: 3px;
+}
+
+.playIcon {
+  width: 22px;
+  height: 22px;
+  fill: #fff;
+  margin-left: 3px;
+}
+
+.iframe {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+}
+
+@media (max-width: 480px) {
+  .playButton {
+    width: 52px;
+    height: 36px;
+    border-radius: 10px;
+  }
+
+  .playIcon {
+    width: 16px;
+    height: 16px;
+  }
+}