add links to explainer series vids (#5007)

Co-authored-by: Duncan Mackenzie <duncanma@duncanmackenzie.net>

Author: jsundai

MARKDOWN_PIPELINE.md

@@ -109,6 +109,7 @@ Each component maps to a strategy in `COMPONENT_REGISTRY` (in `scripts/mdx-to-md
 | `SdkTabs` / `SdkTabs.<Lang>` | `sdk-tabs` | Same, with language labels (`DotNet` → **.NET**) |
 | `CodeSnippet` | `code-snippet` | Fenced code block using the `language` prop |
 | `CaptionedImage`, `EnlargeImage`, `Components.CaptionedImage` | `captioned-image` | `![alt or caption or title](src)` |
+| YouTube/`<iframe>` embeds (often in a styled `<div>`) | strip | Removed; keep a markdown Watch link in surrounding tip/prose for LLMs |
 | `PhotoCarousel` | `photo-carousel` | One `![caption](url)` per entry in the `images`/`captions` arrays |
 | `CallToAction` | `call-to-action` | `- [h3 title](href): p description` |
 | `ReleaseNoteHeader` | `release-note-header` | `> **Public Preview** — Go, Java…` availability note + body blockquote. The self-closing form (`<ReleaseNoteHeader … />`) emits just the note and leaves the page body intact. |

docs/encyclopedia/activities/activities.mdx

@@ -21,6 +21,25 @@ 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.
+
+<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>
+
+:::
+
 An Activity is a normal function or method that executes a single, well-defined action (either short or long running),
 such as calling another service, transcoding a media file, or sending an email message. Activity code can be
 non-deterministic. We recommend that it be [idempotent](/activity-definition#idempotency).

docs/encyclopedia/temporal.mdx

@@ -39,6 +39,25 @@ If a failure occurs, the Workflow Execution can resume from the last recorded ev
 
 ## What is the Temporal Platform? {/* #temporal-platform */}
 
+:::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>
+
+:::
+
 The Temporal Platform consists of supervising software called the [Temporal Service](/temporal-service) and application code bundled as [Worker Processes](/workers#worker-process).
 Together these components create a runtime for your [Temporal Application](/temporal#temporal-application).
 

docs/encyclopedia/workflow/workflow-overview.mdx

@@ -23,6 +23,25 @@ This guide provides a comprehensive overview of Temporal Workflows and covers th
 
 ## Intro to Workflows
 
+:::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>
+
+:::
+
 Conceptually, a workflow defines a sequence of steps. With Temporal, those steps are defined by writing code, known as a Workflow Definition, and are carried out by running that code, which results in a Workflow Execution.
 
 In day-to-day conversations, the term Workflow might refer to Workflow Type, a Workflow Definition, or a Workflow Execution.

scripts/mdx-to-md.mjs

@@ -23,6 +23,7 @@
  *   - <SetupSteps>/<SetupStep>    → prose children + code from the `code={}` prop
  *   - <ZoomPanPinch>              → transparent wrapper, pass inner content
  *   - <ViewSourceCodeNotice href> → plain markdown link line
+ *   - YouTube/HTML embeds         → stripped (keep a markdown Watch link in prose for LLMs)
  *   - imported .md components      → transcluded inline (e.g. <AWSRegions />)
  *   - import / export stmts        → stripped
  *   - {/* MDX comments *​/}         → stripped
@@ -447,6 +448,36 @@ const State = {
   SETUP_STEP: "SETUP_STEP",
 };
 
+/**
+ * If `lines[i]` starts an HTML/JSX video embed (`<iframe>` or styled `<div>`
+ * wrapping one), return the inclusive end index of the block. Otherwise null.
+ * Authors should keep a markdown Watch link in surrounding prose for LLMs.
+ */
+export function findHtmlEmbedEnd(lines, i) {
+  const trimmed = (lines[i] || "").trim();
+  if (/^<iframe\b/i.test(trimmed)) {
+    let j = i;
+    while (j < lines.length) {
+      if (/<\/iframe>/i.test(lines[j]) || /\/>\s*$/.test(lines[j].trim())) {
+        return j;
+      }
+      j++;
+    }
+    return i;
+  }
+  if (/^<div\b/i.test(trimmed) && /style=\{/.test(trimmed)) {
+    let depth = 0;
+    for (let j = i; j < lines.length; j++) {
+      if (/<div\b/i.test(lines[j])) depth++;
+      if (/<\/div>/i.test(lines[j])) {
+        depth--;
+        if (depth === 0) return j;
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Main transform function.
  * @param {string} mdxContent - raw MDX file content
@@ -876,6 +907,12 @@ export function transformMdx(mdxContent, options = {}) {
         admonitionLines = [];
         admonitionType = null;
       } else {
+        // Drop YouTube/HTML embeds inside tips; keep the markdown Watch link.
+        const embedEnd = findHtmlEmbedEnd(lines, i);
+        if (embedEnd !== null) {
+          i = embedEnd;
+          continue;
+        }
         admonitionLines.push(line);
       }
       continue;
@@ -1098,6 +1135,15 @@ export function transformMdx(mdxContent, options = {}) {
       continue;
     }
 
+    // --- HTML/JSX video embeds (YouTube iframes) — strip; keep prose links ---
+    if (state === State.NORMAL) {
+      const embedEnd = findHtmlEmbedEnd(lines, i);
+      if (embedEnd !== null) {
+        i = embedEnd;
+        continue;
+      }
+    }
+
     // --- Image components (self-closing, may span lines) ---
     //     <CaptionedImage|EnlargeImage|Components.CaptionedImage
     //     src="..." alt|caption|title="..." />  →  ![text](src)

tests/test-mdx-to-md.mjs

@@ -565,6 +565,31 @@ test("CaptionedImage uses caption/title when no alt", () => {
   assertContains(markdown, "![Persistence](/diagrams/x.svg)");
 });
 
+test("YouTube iframe embeds are stripped; Watch links kept", () => {
+  const input = `:::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"
+    allowFullScreen
+  ></iframe>
+</div>
+
+:::
+`;
+  const { markdown } = transformMdx(input);
+  assertContains(markdown, "[What Is a Workflow in Temporal?](https://www.youtube.com/watch?v=zLjhNrOKphE)");
+  assertNotContains(markdown, "iframe");
+  assertNotContains(markdown, "youtube.com/embed");
+  assertNotContains(markdown, "<div");
+});
+
 test("PhotoCarousel emits one image per entry with captions", () => {
   const input = `<PhotoCarousel\n  images={[\n    'https://x/a.jpeg',\n    'https://x/b.jpeg',\n  ]}\n  captions={[\n    'First',\n    'Second',\n  ]}\n/>`;
   const { markdown } = transformMdx(input);