How to Add a YouTube Video to a GitHub README (Markdown Guide)

If you've tried pasting a YouTube embed code into a GitHub README, you already know what happens: nothing. The iframe disappears, and your README shows an empty gap where your demo video should be.

That's on purpose. GitHub sanitises the HTML in Markdown files and removes iframes and scripts, so nobody can run code on a repository page. The fix is a small Markdown trick that's become the standard way to show a video in a README.

The clickable thumbnail snippet

Copy this, then replace VIDEO_ID in both places:

[![Watch the demo](https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)

Here's what it does:

• ![Watch the demo](...) shows the video's thumbnail as an image.
• Wrapping it in [ ... ](https://www.youtube.com/watch?v=...) turns that image into a link.

So readers see the video's thumbnail right in the README, and clicking it opens the video on YouTube.

The video ID is the 11-character code after v=. If your link is a youtu.be short link or a Shorts link, our Video ID Finder pulls the ID out for you. There's also a longer explainer in how to find any YouTube video ID.

Picking the right thumbnail size

YouTube stores several thumbnail sizes for every video. These are the ones worth knowing:

If maxresdefault.jpg shows a small grey placeholder instead of your thumbnail, switch to hqdefault.jpg. You can preview every size for a video with our Thumbnail Downloader before you choose.

Controlling the size

Markdown images always display at their natural size, up to the width of the page. To make the thumbnail smaller, use an HTML img tag. GitHub allows that, as long as it's not an iframe:

<a href="https://www.youtube.com/watch?v=VIDEO_ID">
  <img src="https://img.youtube.com/vi/VIDEO_ID/hqdefault.jpg" alt="Watch the demo" width="480">
</a>

You can also wrap it in <p align="center"> to centre it, which looks tidy at the top of a README.

Adding a play button

A bare thumbnail doesn't always look clickable. Two easy fixes:

• Make your own image. Download the thumbnail, add a play icon in any image editor, commit it to your repo (for example in a docs/ folder) and use that path in the snippet instead.
• Say it in the alt text and caption. A line like "Click to watch the 2-minute demo" under the image does the job.

The other option: upload the video to GitHub

For short screen recordings, there's a native alternative. In the GitHub web editor (for a README, issue or pull request), you can drag an MP4 or MOV file straight into the text box. GitHub uploads it and inserts a link that renders as a real video player.

This works well for:

• 10 to 30 second demos of a feature.
• Bug reproductions in issues.
• UI changes in pull requests.

The limits: files must be fairly small (GitHub caps the size, and larger plans get more room), and it's not the place for a long tutorial. For anything more than a minute or two, YouTube is still the better home, because it handles streaming, quality switching and captions for you.

Animated GIF previews

Another popular approach is to put a short GIF of the app in the README, and link it to the full video on YouTube. Readers see movement immediately without clicking anything. Keep GIFs short and small (a few MB at most) or the README will be slow to load.

What about GitHub Pages and docs sites?

GitHub Pages is different. It's a real website, so a normal YouTube iframe works fine there. The same goes for docs tools built on top of Markdown, like Docusaurus, MkDocs or VitePress, which let you include HTML.

For those, generate a clean, responsive embed with our Embed Code Generator. If your docs site is built with React, our guide to embedding YouTube in React and Next.js has components you can drop straight in.

Copy-ready summary

For most READMEs, this one line is all you need:

[![Watch the video](https://img.youtube.com/vi/VIDEO_ID/hqdefault.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)

Swap in your ID, commit, and your project has a video that works on every device.