Adds video guidance to syntax ref guide

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

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