diff --git a/.github/instructions/docs-writing.instructions.md b/.github/instructions/docs-writing.instructions.md index 9dd6348bb5f..0eb007bc376 100644 --- a/.github/instructions/docs-writing.instructions.md +++ b/.github/instructions/docs-writing.instructions.md @@ -118,7 +118,10 @@ Use the agreed framing to guide the plan, scope, structure, terminology, prerequ * Use videos only when they add value. * Videos have a descriptive and meaningful title that starts with "Video showing" or "Video of" and ends with ".". -* For embedded videos, you MUST use `youtube-nocookie.com` instead of `youtube.com`. +* Do not embed YouTube videos with an `iframe`. Use linked-image Markdown with a locally stored thumbnail. The site automatically opens external Markdown links in a new tab. +* Store blog post thumbnails alongside the Markdown file. For other content, store them in `images//`. +* The thumbnail alt text is the link's accessible name. It must identify the video and announce that the link opens in a new tab, for example `[![Watch