Markdown conquered documentation, and documentation keeps needing video. The awkward part: core Markdown has no syntax for video. Images, yes, one exclamation mark and done. Video, no, every renderer has its own opinion. The result is a scattered landscape of workarounds, some elegant, some fragile.

Here is what actually works where, in 2026.

The short answer by platform

GitHub READMEs

GitHub renders video files placed in the repo itself. Drag an MP4 into the README editor or reference it with relative Markdown image syntax:


It autoplays muted and loops, which is perfect for short demos. Keep files small, under roughly 10 MB is polite to cloners, and remember the file lands in every clone forever.

GitHub issues, discussions, PRs

Paste a platform URL into the body and GitHub renders a player card for major video sites. For your own hosted clips on smaller platforms, paste the direct watch-page URL and it will linkify cleanly even without an inline player.

GitLab

Similar: repo-relative video in Markdown renders a player; platform links turn into rich cards.

Wikis (MediaWiki and friends)

MediaWiki uses custom tags rather than Markdown for embedding, with extensions handling platform players. For Markdown-based wikis, see the HTML route below.

Static site generators and docs tools

Most (MkDocs, Docusaurus, Hugo, and friends) ship extensions or shortcodes for embedding video, either as platform iframes or self-hosted files with a player component. Check your tool's shortcode before improvising.

The universal fallback: raw HTML

Markdown tolerates inline HTML almost everywhere, which makes the iframe and video tags portable escape hatches:

<iframe src="https://example.com/embed/xyz" width="640" height="360" frameborder="0" allowfullscreen></iframe>

<video src="demo.mp4" controls muted width="640"></video>

Caveats: some strict renderers (certain wikis, chat apps) strip raw HTML for security, so test before relying on it in a new environment.

Linking to your own hosted clips

For documentation of your own projects, the cleanest pattern is often the simplest: upload the demo clip to a video platform, then either embed it via the tool's supported mechanism or drop a plain link with a thumbnail-styled callout:

Demo

[Watch the 30-second demo](https://example.com/watch/demo)

A watch page on a fast video host, like a s.pub page for short clips, gives viewers adaptive playback and you a permanent URL that survives doc reorganizations. Some Markdown renderers will even show a rich preview card for the link.

Animated demos: GIF or short video?

For a README hero demo, the trade-offs:

GIF

Renders everywhere, autoplays everywhere, no click needed. Costs: enormous files for the same content, 256 colors, no audio ever.

Repo MP4 via image syntax

GitHub-native, small, high quality. Costs: GitHub-only behavior, weight in clones.

Linked platform video

Full quality, real analytics, works everywhere as a link. Costs: one click to leave the page.

The pragmatic stack used by popular projects: a short looping GIF or repo MP4 for the hero moment at the top of the README, platform links for longer walkthroughs further down.

Getting the clip small enough to embed

Screen content compresses extremely well. Before committing any video to a repo or docs folder:

ffmpeg -i raw-capture.mp4 -c:v libx264 -crf 26 -preset slow -vf "scale=-2:720" -an -movflags +faststart demo.mp4

Dropping audio (-an) alone halves most UI captures, and demos rarely need sound. A 60-second capture routinely lands under 5 MB.

Checklist for docs video that lasts

Prefer native mechanisms (repo video on GitHub, shortcodes in your generator) over raw HTML. Keep repo-resident files small and few; host anything longer externally and link it. Name files like you name code, versioned and obvious. Test the render on the actual destination, because Markdown rendering is where embeds go to die. And keep source recordings somewhere durable, because the day will come when the demo needs an update, and re-recording from scratch is always worse than re-editing.