3.3 内嵌 HTML 的能力与边界

3.3 内嵌 HTML 的能力与边界

Markdown 原生就允许混写 HTML：行内标签随处可用，块级标签单独成行。它像一扇逃生舱——语法覆盖不到的需求（折叠内容、彩色徽章、键盘按键标记）从这里溜出去解决。但这扇门有代价：可移植性。这一节划清楚能力边界。

行内 HTML：早就用上了

你在前两章其实已经用过行内 HTML 了：

单元格内换行用<br/>标签
H<sub>2</sub>O 与 2<sup>10</sup> 的上下标
按键写作 <kbd>Ctrl</kbd> + <kbd>S</kbd>
​

kbd 标签渲染成键帽样式，写操作手册时体验极佳。这类"单标签、无嵌套"的行内 HTML 几乎所有 Markdown 环境都支持，放心用。

块级 HTML：能力大，坑也大

块级标签单独成行开始一个 HTML 区块，区块内 Markdown 语法全部失效：

折叠内容：details 的正确姿势

块级 HTML 里日常价值最高的是折叠区块——长日志、大段配置、可选的深入说明，折叠起来不占阅读流，需要的人点开即得：

<details>
<summary>完整启动日志（点击展开）</summary>

```text
[10:02:11] loading config ...
[10:02:12] worker started, pid=4821
[10:02:13] ready, listening on :8080
```

</details>
​

两个细节决定成败：其一，summary 标签单独占一行，写成"点开看什么"的描述而不是干巴巴的"详情"；其二，details 内部与 summary 之间留一个空行，块内就重新回到 Markdown 解析——上面例子里围栏代码块因此照常高亮，不留空行的话它会被当成纯文本。折叠的适用判据与脚注一脉相承：对多数读者是噪音、对少数读者是刚需的内容才折叠；把核心结论折叠起来是对读者耐心的透支。

安全面：为什么你的 HTML 会消失

写了一行样式或脚本，保存后渲染出来却空空如也——这不是 bug，是几乎所有托管平台的安全过滤在起作用。脚本、内联框架、样式标签会执行任意代码或注入第三方内容，平台一律剥掉；有的平台更严格，class 与 style 属性也一并清洗。被剥掉的标记通常不留痕迹，于是"我明明写了"与"页面上没有"之间没有报错可查。排查的顺序：先确认不是拼写与闭合问题，再去平台文档里查 HTML 白名单——白名单里没有的写法，换实现思路（比如想要的颜色高亮，改用平台支持的提示容器语法），不要与过滤器较劲。

这条安全边界也提示了 HTML 使用的总纪律：行内小标签与 details 折叠之外，别把文档的骨架托付给 HTML。原因有三层。可移植性——换一个平台或渲染器，白名单随时变化，纯 Markdown 语法则处处通行。可维护性——HTML 嵌套一深，Markdown 的"源码即排版"优势荡然无存，同事接手时面对的是另一门标记语言。一致性——同类信息若一半用 Markdown 语法一半用 HTML 实现，文档风格会分裂成两套。判断某个 HTML 需求是否越界的口诀很简单：它是在补 Markdown 的语法空白（换行、键帽、折叠），还是在绕开 Markdown 的工作方式（手写表格标签、用样式强制排版）？前者是逃生舱的正常用途，后者是往舱门外跳。

本节要点回顾

• 行内小标签放心用（br/sub/sup/kbd），块级 HTML 单独成行且区内 Markdown 失效。
• 折叠内容用 details，标签与内容之间留空行以恢复 Markdown。
• script/iframe/style 会被安全过滤，"消失的 HTML"先查白名单。
• 纪律：HTML 只做行内微调与折叠，结构永远交给纯 Markdown。

折叠面板的组合用法

details 最实用的进阶用法是套清单与代码块做"附录面板"。长教程里的完整配置文件、全部测试输出，塞正文拖垮节奏，删掉又怕读者要查——折叠面板正是为这类"少数时候需要"的内容准备的。一段可复用的骨架：

<details>
<summary>完整配置文件（点开查看）</summary>

```yaml
server:
  port: 8080
  timeout_ms: 3000
```

</details>
​

注意 summary 标签之后、代码围栏之前的空行：没有它，YAML 会被当 HTML 文本而非代码块渲染。这个"空行恢复 Markdown"的规则是折叠面板好用与否的分水岭，务必动手验证一次。折叠面板的纪律同样是密度：每屏至多一个，页首不放（读者不该一进来就点开折叠才能读）；summary 文字要写清内容与规模（"完整配置（38 行）"），让读者决定值不值得点。

kbd 与细节标签的实用组合

再给两个高频实用标签的具体用法。<kbd> 渲染为键帽样式，写快捷键说明时辨识度远高于引号：按 <kbd>Ctrl</kbd> + <kbd>S</kbd> 保存，输出后 Ctrl 与 S 带边框小方块，读者一眼识别为按键而非文字。<span style="color:..."> 这类带行内样式的写法则要克制：它能让某几个字变红，但颜色信息只对视觉读者存在，读屏与纯文本环境全部丢失——强调仍应交给加粗，颜色只用于确有语义且文字已自解释的补充（如"红：危险操作"配图例说明）。这条边界与 3.3 的总纪律一致：HTML 做微调，不承载信息本身。

HTML 过滤的验尸方法

内容凭空消失时，最快的诊断是比对中间产物：如果平台提供"查看渲染后 HTML"（多数站点的页面右键查看源码即可），对比你写的标签是否还存在于输出里。标签整个不在——被过滤器吞了，白名单问题；标签在但样式不对——CSS 层问题，与 Markdown 无关。这个二分法五分钟内就能把"消失了"的谜团定位到责任层。顺带一提，链接里的 target="_blank"、class 属性被剥离是常见现象（安全策略），不属故障，设计上就该接受。