Markdown 嵌入视频

写技术文档或者做项目展示的时候，经常需要嵌入一个视频演示——比如产品功能录屏、教程视频、会议录像。Markdown 本身没有视频语法，不像 Markdown 图片 有 ![]() 这么方便。但好在 Markdown 支持内联 HTML，用 iframe 就能把视频嵌进去。今天就把各种嵌入方式、各平台的兼容情况、以及不支持的时候怎么办，一次讲清楚。

为什么 Markdown 没有原生的视频语法

先说一个事实：标准 Markdown 和 CommonMark 规范里都没有定义视频嵌入语法 。Markdown 最初设计的目标是"易读易写的纯文本格式"，视频嵌入超出了这个范围。所以不管你想 embed YouTube 视频、Vimeo 视频，还是本地视频文件，都得借助 HTML。

具体来说有这几种思路：

1. HTML <iframe> 标签：嵌入在线视频平台（YouTube、Vimeo、Bilibili）
2. Markdown 图片链接：用视频缩略图做"假嵌入"，点击跳转到视频页面
3. HTML5 <video> 标签：嵌入本地视频文件
4. 平台特定扩展语法：少数编辑器或插件支持的自定义语法

下面一个一个来。

用 iframe 嵌入 YouTube 视频

YouTube 是最常见的视频嵌入需求。关键是拿到视频的 embed URL——它和普通观看地址不同，用的是 youtube.com/embed/ 路径：

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen>
</iframe>

其中 dQw4w9WgXcQ 是视频 ID，就是 YouTube 视频链接 watch?v= 后面的那串字符。

怎么获取视频 ID

YouTube 视频链接一般长这样：https://www.youtube.com/watch?v=dQw4w9WgXcQ，v= 后面的值就是视频 ID。把它拼到 https://www.youtube.com/embed/ 后面就行。

如果链接是短链接格式 https://youtu.be/dQw4w9WgXcQ，最后那段也是视频 ID。

iframe 各属性解释

说实话，直接复制上面的代码改个视频 ID 就够用了。但了解一下各属性的含义有好处：

allow 属性里的内容是 YouTube 建议的安全权限列表，直接照抄就好。如果你不介意少几个功能，只保留 allowfullscreen 也能正常播放。

用 iframe 嵌入 Vimeo 视频

Vimeo 的嵌入方式和 YouTube 几乎一样，只是 embed URL 不同：

<iframe width="640" height="360"
  src="https://player.vimeo.com/video/19706846"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen>
</iframe>

Vimeo 的视频 ID 就是链接最后的数字，比如 https://vimeo.com/19706846 里的 19706846。注意 Vimeo 的播放器域名是 player.vimeo.com，不是 www.vimeo.com。

顺便提一句，Vimeo 的嵌入地址格式和普通观看地址完全不同。如果你直接拿 https://vimeo.com/19706846 塞进 iframe 的 src 里，是不会有播放器的——必须用 player.vimeo.com/video/ 这个路径。

用 iframe 嵌入 Bilibili 视频

对于中文用户来说，B 站（Bilibili）可能是更常用的视频平台。嵌入 B 站视频也用 iframe：

<iframe width="640" height="360"
  src="//player.bilibili.com/player.html?bvid=BV1xx411c7mD&page=1"
  frameborder="0"
  allowfullscreen>
</iframe>

B 站的嵌入地址需要用 BV 号（BV1xx411c7mD），就是视频链接里的那串 ID。page=1 表示第一P（分P视频的话可以改成对应页数）。

BV 号在视频链接里就能找到，比如 https://www.bilibili.com/video/BV1xx411c7mD 中 BV 开头的那串就是。

缩略图链接方案：全平台通用的替代方案

上面说的 iframe 方案有一个大问题：很多平台会过滤掉 iframe 标签。最典型的就是 GitHub——它的 HTML 白名单里不包含 iframe 。你在 GitHub README 里写 iframe，推上去一看，什么都没有。

这时候最靠谱的替代方案是用 Markdown 的图片+链接语法，做一个"看起来像视频"的缩略图：

[![视频标题](https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg)](https://www.youtube.com/watch?v=dQw4w9WgXcQ)

这行代码做了一件事：显示 YouTube 视频的缩略图，点击后跳转到视频页面。它用的是纯 Markdown 语法（Markdown 链接 + Markdown 图片），所以在所有平台都能正常显示 。

YouTube 的缩略图 URL 是有规律的，不需要手动截图：

一般用 hqdefault.jpg 就够了，清晰度不错，加载也快。

加个播放按钮

缩略图看起来毕竟不像视频播放器。一个常用的技巧是在缩略图上叠加一个播放按钮图标——不过这需要 CSS 或 SVG，在纯 Markdown 里做不到。最简单的方式是让缩略图本身带播放按钮，YouTube 的 hqdefault.jpg 默认就有中间那个黑色半透明条。

我之前在一个开源项目的 README 里用这个方法放了一个功能演示视频。虽然点击后跳转到 YouTube 而不是直接播放，但至少用户能看到视频封面，知道这里有个视频可以看。比单独放一个文字链接好多了——文字链接你根本不会注意到它是视频。

HTML5 video 标签：嵌入本地视频

如果你有一个本地的 .mp4 视频文件想嵌入（比如放在同一仓库里的演示录屏），可以用 HTML5 的 <video> 标签：

<video width="640" height="360" controls>
  <source src="demo.mp4" type="video/mp4">
  你的浏览器不支持 video 标签
</video>

controls 属性会显示播放控制条（播放/暂停、进度条、音量）。src 可以是相对路径或绝对 URL。

不过说实话，这种方式限制很大。GitHub 会过滤 <video> 标签，很多在线 Markdown 编辑器也不支持。它更适合用在 Jekyll、Hugo 这类自己控制的静态站点里。

响应式视频嵌入

固定宽高的 iframe 在手机上会很难看——要么溢出屏幕，要么挤成一团。如果你在自己搭的网站（Jekyll、Hugo 等）里用 Markdown，可以用 CSS 做响应式适配：

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
    src="https://www.youtube.com/embed/dQw4w9WgXcQ"
    frameborder="0"
    allowfullscreen>
  </iframe>
</div>

这里 padding-bottom: 56.25% 是 16:9 宽高比的百分比表示（9÷16 = 0.5625）。iframe 用绝对定位铺满容器，不管屏幕多宽，视频播放器始终维持 16:9 比例。

如果你用现代浏览器，还有更简洁的写法：

<div style="aspect-ratio: 16/9; width: 100%;">
  <iframe style="width: 100%; height: 100%;"
    src="https://www.youtube.com/embed/dQw4w9WgXcQ"
    allowfullscreen>
  </iframe>
</div>

aspect-ratio 是 CSS 的新属性，主流浏览器都支持了，写起来简洁很多。不过 GitHub 会过滤 inline style，所以这个方案只适用于你自己的网站。

我之前给一个 Jekyll 博客加视频的时候就踩了坑——直接用 width="560" height="315" 的固定尺寸，结果手机上看视频直接撑出了屏幕，得横向滚动才能看完。后来换成 aspect-ratio 方案，手机和桌面都能正常显示。

平台特定扩展语法

少数平台提供了自定义的 video embed 语法，但这些语法只在特定环境里有效：

markdown-it-video 插件

@[youtube](dQw4w9WgXcQ)
@[vimeo](19706846)

这个语法由 markdown-it-video 插件提供，使用 markdown-it 作为解析器的项目（比如用 Node.js 搭建的站点）可以装这个插件来支持 。

October CMS

!![560x315](https://www.youtube.com/embed/5xK8RK54IAc)

October CMS 的 Markdown 解析器支持这个特殊语法，它会被转换为标准的 iframe 嵌入。

这些自定义语法都不通用，换个平台就失效了。除非你确定只在特定环境里用，否则还是老老实实写 iframe 更靠谱。

各平台兼容性对比

不同平台对视频嵌入的支持差异很大，这里整理了主流平台的情况：

几个关键点：

• GitHub 是限制最严的平台，iframe 和 video 都不支持，只能用缩略图链接方案
• GitLab 反而支持 iframe，如果你用 GitLab 管理文档，可以直接嵌入视频
• Obsidian 和 Typora 对视频嵌入最友好，iframe 和 video 标签都能正常工作
• Notion 有自己的嵌入方式，用 /embed 命令粘贴视频链接就行，不需要写代码

实际使用场景

项目 README 里放演示视频

## 功能演示

点击查看录屏演示：

[![功能演示视频](https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg)](https://www.youtube.com/watch?v=dQw4w9WgXcQ)

GitHub 上最常见的方式。虽然不是真正的嵌入式播放，但至少能看到视频封面。

技术博客嵌入教程视频

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="教程视频"
  allowfullscreen>
</iframe>

Jekyll、Hugo 等博客系统里可以直接用 iframe，读者不用离开页面就能看视频。

Obsidian 笔记里嵌入会议录像

## 2024-03-15 产品评审会议

<iframe width="560" height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  allowfullscreen>
</iframe>

在 Obsidian 里做会议笔记时，把录像直接嵌在笔记里，回顾的时候不用再翻聊天记录找视频链接。

常见问题

GitHub README 里怎么嵌入视频？

GitHub 不支持 <iframe> 和 <video> 标签。唯一的办法是用缩略图链接：

[![演示视频](https://img.youtube.com/vi/VIDEO_ID/hqdefault.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)

这不是真正的视频嵌入，而是显示视频缩略图，点击后跳转到 YouTube 播放 。

Markdown 有视频语法吗？

没有。标准 Markdown 和 CommonMark 规范都不包含视频嵌入语法 。所有视频嵌入都需要借助 HTML 标签（iframe 或 video）。

为什么我的 iframe 不显示？

最常见的原因有两个：

1. 平台过滤了 iframe：GitHub、部分在线编辑器会出于安全考虑，把 iframe 标签整个删掉。检查一下你的目标平台是否在白名单里支持 iframe。
2. embed URL 格式不对：YouTube 的 iframe src 必须是 youtube.com/embed/VIDEO_ID，而不是 youtube.com/watch?v=VIDEO_ID。Vimeo 的必须是 player.vimeo.com/video/ID。用错了地址 iframe 会显示空白或报错。

如何让嵌入的视频自适应屏幕宽度？

用 CSS 的 aspect-ratio 属性包裹 iframe：

<div style="aspect-ratio: 16/9; width: 100%;">
  <iframe style="width: 100%; height: 100%;"
    src="https://www.youtube.com/embed/VIDEO_ID"
    allowfullscreen>
  </iframe>
</div>

这个方案需要目标平台支持 inline style（GitHub 不支持）。

Bilibili 视频怎么获取嵌入代码？

在 B 站视频页面点击"分享"按钮，选择"嵌入代码"即可获得完整的 iframe 代码。或者手动拼接：//player.bilibili.com/player.html?bvid=你的BV号。

参考来源

: Markdown Guide — Extended Syntax: MDN Web Docs — iframe 元素: GitHub Docs — 在 Markdown 中编写表达式: GitHub — markdown-it-video 插件