专题指南

Markdown 中嵌入 HTML

Markdown 已覆盖大部分常见结构。偶尔嵌入一小段 HTML，可以补足明确的展示需求——前提是目标输出环境已知，而且 Markdown 本身仍能完整传达内容。

MarkIOY Team · 2026 年 8 月 11 日 · 约 9 分钟阅读

HTML 是可选扩展，不是可移植性保证。先用标准 Markdown 写好文档；只有遇到明确的展示需求时才加入 HTML，并在文件实际会被阅读或发布的每个环境中测试。

HTML 在何时有用

许多 Markdown 解析器会把一部分 HTML 原样交给最终页面。这样可以补足核心 Markdown 不擅长的结构：可折叠详情、带尺寸的图片、键盘快捷键，或简短的媒体嵌入。

但 Markdown 文件不是一个不受限制的网页。它可能被静态站点生成器、仓库查看器、笔记软件、邮件客户端或知识库渲染；不同工具可能允许、转义、删除或过滤 HTML。

适合放置会打断主阅读流的补充说明。重要结论应写在折叠区之前，因为有些读者不会看到或打开它。

<details>
<summary>为什么这是可选内容？</summary>

需要时可以展开查看这段补充说明。
</details>

渲染效果

正在准备渲染效果…

Markdown 图片通常更可移植。只有当目标渲染器会遵守图片尺寸，且版面需要相对稳定的最大宽度时，HTML 图片才有意义。

<img src="/editor-visual.png"
     alt="同时打开源码与预览视图的文档"
     width="720">

渲染效果

正在准备渲染效果…

不要把关键布局依赖在 style 属性上：它经常会被删除，固定像素宽度在窄屏上也可能体验很差。

按下 <kbd>⌘</kbd> + <kbd>S</kbd> 保存。

<mark>发布前请复核这项假设。</mark>

渲染效果

正在准备渲染效果…

这类行内元素可以丰富表达，无须脚本或定制样式。即使渲染器删除标签，文字本身仍然保留。

只有在目标渲染器允许，且远端站点允许被嵌入时，iframe 才能放入视频、地图或交互式原型。嵌入前后都应提供一个普通链接。

<p><a href="https://markioy.com/">直接打开 MarkIOY</a></p>
<iframe src="https://markioy.com/" title="MarkIOY 首页" loading="lazy"></iframe>

渲染效果

正在准备渲染效果…

文件去向	可能发生什么	应对方式
严格的 Markdown 解析器	HTML 被当作普通文字显示，或被转义。	重要内容使用普通 Markdown。
代码仓库或 CMS	不安全的标签、属性会被移除。	默认有安全过滤，只使用其文档明确允许的子集。
知识库或聊天工具	为保证一致性，HTML 可能整体被禁用。	提供 Markdown 等价表达或普通链接。
静态网站	HTML 可以渲染，但模板或插件也可能再次处理它。	构建并预览生产环境的网站。
嵌入页面	iframe 可能被 CSP 或 frame-ancestor 策略拦截。	链接到目标页面，不要完全依赖嵌入。

安全过滤本身是必要的保护。脚本、onclick 之类的事件属性、内嵌样式、表单和框架可能带来跨站脚本、追踪或钓鱼风险。即使片段在本地浏览器预览正常，平台仍可能静默移除它们。

<button onclick="this.textContent = '已在沙箱中执行'">运行本地 HTML</button>
<script>document.body.dataset.demo = 'active'</script>

渲染效果

正在准备渲染效果…

标题、列表、链接、图片、表格、代码围栏和 Mermaid 源码已经覆盖大多数文档需求。如果删除一个 HTML 标签后文档就失去意义，说明内容过度依赖某个渲染器的私有能力。

把关键信息写在 details 之外；每个嵌入框都提供链接；每张图片都提供描述。把增强型 HTML 当作渐进增强：它可以改善首选视图，但不能成为信息或操作的唯一入口。

图片和嵌入框应使用 HTTPS 地址，并确保来源可控或可信。不要嵌入凭据、私密查询参数，或没有评估隐私与数据收集的第三方组件；文档的传播范围往往比写作时的场景更大。

检查源码、编辑器预览、发布后的页面，以及重要的导出格式；也要测试窄屏和键盘操作。真正重要的渲染器，是你的读者实际正在使用的那个。

先让纯 Markdown 独立表达清楚，再用最小的 HTML 片段解决已经验证的展示需求。