From 4ced702c45df9b286162c33f3de84ad692666395 Mon Sep 17 00:00:00 2001
From: Janeen Roberts <janeen.roberts@elastic.co>
Date: Tue, 5 May 2026 17:38:57 -0400
Subject: [PATCH 1/2] Adds video guidance to syntax ref guide

---
 docs/_docset.yml      |  1 +
 docs/syntax/videos.md | 60 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 docs/syntax/videos.md

diff --git a/docs/_docset.yml b/docs/_docset.yml
index 7b8272b25..8c56fc0d0 100644
--- a/docs/_docset.yml
+++ b/docs/_docset.yml
@@ -142,6 +142,7 @@ toc:
       - file: frontmatter.md
       - file: icons.md
       - file: images.md
+      - file: videos.md
       - file: kbd.md
       - file: math.md
       - file: diagrams.md
diff --git a/docs/syntax/videos.md b/docs/syntax/videos.md
new file mode 100644
index 000000000..3f710dc99
--- /dev/null
+++ b/docs/syntax/videos.md
@@ -0,0 +1,60 @@
+# Videos
+
+Videos can supplement documentation to demonstrate features, workflows, or complex procedures. Embed videos using standard Markdown link and image syntax.
+
+:::{important}
+Video link URLs must use **lowercase characters only**. Mixed-case URLs cause build failures in integrations documentation.
+:::
+
+## Elastic-hosted videos (recommended)
+
+For Elastic-hosted videos on `videos.elastic.co`, use a clickable thumbnail that links to the video. This displays a preview image that readers can click to watch the video.
+
+```markdown
+[![Video description](https://play.vidyard.com/VIDEO_ID.jpg)](https://videos.elastic.co/watch/VIDEO_ID?)
+```
+
+**Example:**
+
+```markdown
+[![Attack Discovery video](https://play.vidyard.com/eT92arEbpRddmSM4JeyzdX.jpg)](https://videos.elastic.co/watch/eT92arEbpRddmSM4JeyzdX?)
+```
+
+This renders as a clickable thumbnail image. When clicked, it opens the video on `videos.elastic.co`.
+
+### Finding the video ID
+
+The video ID is the alphanumeric string in the Vidyard URL. For example, in `https://videos.elastic.co/watch/eT92arEbpRddmSM4JeyzdX`, the video ID is `eT92arEbpRddmSM4JeyzdX`.
+
+Use this same ID for both:
+- The thumbnail URL: `https://play.vidyard.com/VIDEO_ID.jpg`
+- The video URL: `https://videos.elastic.co/watch/VIDEO_ID?`
+
+## YouTube videos
+
+For YouTube videos, use a simple text link:
+
+```markdown
+[Video title](https://www.youtube.com/watch?v=VIDEO_ID)
+```
+
+**Example:**
+
+```markdown
+Refer to the [Threadpool Rejections video](https://www.youtube.com/watch?v=auZJRXoAVpI) for a troubleshooting walkthrough.
+```
+
+## Best practices
+
+**DO:**
+
+- ✅ Introduce videos with context, such as "The following video demonstrates these steps (click to watch)."
+- ✅ Use descriptive alt text that explains the video content
+- ✅ Use lowercase characters in all video URLs
+- ✅ Use Elastic-hosted videos on `videos.elastic.co` when available
+
+**DON'T:**
+
+- ❌ Use mixed-case characters in video URLs—this causes build failures for integrations
+- ❌ Rely solely on videos for critical information — always provide text alternatives
+- ❌ Embed videos directly in the page—use clickable thumbnails instead

From 3a126e0468e8205bbadf4b39bc5f72fb9af6dc93 Mon Sep 17 00:00:00 2001
From: Janeen Roberts <janeen.roberts@elastic.co>
Date: Wed, 6 May 2026 10:33:41 -0400
Subject: [PATCH 2/2] Update videos.md

---
 docs/syntax/videos.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/syntax/videos.md b/docs/syntax/videos.md
index 3f710dc99..02c1a1336 100644
--- a/docs/syntax/videos.md
+++ b/docs/syntax/videos.md
@@ -3,7 +3,7 @@
 Videos can supplement documentation to demonstrate features, workflows, or complex procedures. Embed videos using standard Markdown link and image syntax.
 
 :::{important}
-Video link URLs must use **lowercase characters only**. Mixed-case URLs cause build failures in integrations documentation.
+For integrations documentation, any **file paths or custom URL slugs** in video links must use lowercase characters only. Mixed-case paths cause build failures. Note that Vidyard video IDs (like `eT92arEbpRddmSM4JeyzdX`) are assigned by the service and are acceptable as-is.
 :::
 
 ## Elastic-hosted videos (recommended)
@@ -50,11 +50,11 @@ Refer to the [Threadpool Rejections video](https://www.youtube.com/watch?v=auZJR
 
 - ✅ Introduce videos with context, such as "The following video demonstrates these steps (click to watch)."
 - ✅ Use descriptive alt text that explains the video content
-- ✅ Use lowercase characters in all video URLs
+- ✅ Use lowercase file paths and custom URL slugs in integrations documentation
 - ✅ Use Elastic-hosted videos on `videos.elastic.co` when available
 
 **DON'T:**
 
-- ❌ Use mixed-case characters in video URLs—this causes build failures for integrations
+- ❌ Use mixed-case file paths or custom URL slugs in integrations documentation—this causes build failures
 - ❌ Rely solely on videos for critical information — always provide text alternatives
 - ❌ Embed videos directly in the page—use clickable thumbnails instead