Markdown与HTML的关系

Markdown 不是独立的展示格式，而是 HTML 的书写简化层，最终产物就是 HTML。理解这条渲染管线，即可解释内嵌 HTML、实体解码时机等一众”怪象”。语法速查看 Markdown，HTML 本体见 HTML。

渲染管线

Markdown（John Gruber, 2004）的设计定位是 “a text-to-HTML conversion tool”：用易写的源语法编译成 HTML，.md 文件本身不负责显示：

.md 源文件 ──Markdown 解析器──▶ HTML 字符串 ──浏览器引擎──▶ 页面

• Obsidian：Electron 应用，内嵌 Chromium，阅读模式与 Live Preview 渲染的都是 HTML
• GitHub / 博客发布：先把 Markdown 编译成 HTML 再渲染

内嵌 HTML 的机制

Markdown 只覆盖常用结构，覆盖不到的（<details>、<kbd>、<sup> 上下标等）直接写原生 HTML——这是规范（CommonMark 的 raw HTML）的一等公民特性，不是 hack。

解析器对 HTML 标签与实体透传（pass-through）：不翻译、原样写入输出 HTML，交给浏览器解析：

源文件：  正文 <code>&#124;</code> 结尾
md 输出：  正文 <code>&#124;</code> 结尾    ← 原样透传
浏览器：  &#124; 是 HTML 实体 → 解码为 |

实体解码时机

管线中有两个解析器：Markdown 决定哪些字符活着到达浏览器，HTML 层才负责实体解码。代码 span 的语义是逐字保留——Markdown 提前把 & 转义为 &，实体到达浏览器时已失效：

位置与写法	Markdown 层	浏览器层	渲染结果
|	实体透传	解码	✅ |
`|`	& 转义为 &，实体失效	无法解码	❌ 字面 |
<code>&#124;</code>	标签与实体均透传	解码	✅ |

一句话：实体是 HTML 语法，只在 HTML 上下文里活；代码 span 属于 Markdown 语义，实体进不去。

实战：表格内显示字面竖线

表格中裸 | 是列分隔符，必须转义，且 Obsidian 与 GFM 行为不一致：

写法	普通文本单元格	行内代码内
|	✅ |	❌ Obsidian 显示 |（斜杠可见；GitHub 正常）
|	✅ |	❌ 字面 |
<code>&#124;</code>	✅ |	✅ |，唯一跨引擎可靠写法

• \| 只声明”别在此拆列”，代码 span 内 Obsidian 不剥离反斜杠（GFM 会剥离）
• 数学公式内的竖线用 \vert
• <code> 标签救不了 wiki-link：inline HTML 标签之间的文本仍走 markdown inline 解析，`[[笔记|别名]]` 这类写法会被 wiki-link 规则吃成链接。含管道的双链语法只能进 fenced code block
• 实例见 正则表达式 元字符表的或运算符一行；本文两张表的”写法”列即按上述规则用各场景的正确转义写成