Chapter 06 / 10

引用块、分隔线与 HTML

块级引用的嵌套与应用、分隔线语法、内嵌 HTML 的用法与平台差异

块级引用（Blockquotes）

用 > 前缀创建引用块，对应 HTML 的 <blockquote> 元素。引用块在视觉上会缩进显示，并通常有左侧边框，用于引用他人的话、重要说明、警告等。

基本语法

源码
> 这是一段引用文字。
> 同一行 > 不需要连续，
> 多行内容会合并成一个段落。

> 这是第二个引用块（空行分隔）。
渲染效果
这是一段引用文字。同一行 > 不需要连续，多行内容会合并成一个段落。
这是第二个引用块（空行分隔）。

引用块内的多段落

引用块内部也可以有多个段落，用空行（但都加 > 前缀）分隔：

> 这是引用的第一段。
>
> 这是引用的第二段（中间有一行 `>`）。
>
> 这是第三段。
INFO空行分隔符（> 空行）在引用块内部创建段落边界。如果空行完全不加 >，会结束引用块，开始普通段落。注意区分这两种情况。

引用块内嵌套 Markdown 元素

引用块内部可以使用完整的 Markdown 语法：

> ## 引用块内的标题
>
> 引用块内可以有**加粗**、*斜体*、`代码`等格式。
>
> 也可以有列表：
> - 第一点
> - 第二点
>
> 还可以有代码块：
> ```python
> print("Hello from inside a blockquote!")
> ```

引用块内的标题

引用块内可以有加粗、斜体、代码等格式。

也可以有列表：

  • 第一点
  • 第二点

多级嵌套引用

用多个 > 符号创建嵌套引用（类似邮件回复的引用层级）：

源码
> 一级引用
>
>> 二级引用（嵌套）
>>
>>> 三级引用（更深）
>>
>> 回到二级
>
> 回到一级
渲染效果
一级引用
二级引用（嵌套）
三级引用（更深）
回到二级
回到一级
TIP（适度嵌套）在实际写作中，超过 2 层嵌套引用的可读性会急剧下降。如果需要展示"答复中的答复中的答复"这样的结构，考虑改用有序列表或专门的视觉布局。邮件类引用超过 2 层通常说明对话链太长，需要整理信息。

GitHub Alert（GFM 告警块）

GitHub 从 2023 年起支持特殊的告警块语法，在引用块第一行用 > [!TYPE] 格式触发：

源码
> [!NOTE]
> 这是一个信息提示，用于补充说明。

> [!TIP]
> 这是一个技巧提示，帮助读者更好完成任务。

> [!IMPORTANT]
> 这是重要信息，用户必须了解。

> [!WARNING]
> 这是警告，操作可能导致问题。

> [!CAUTION]
> 这是危险提示，操作可能导致数据丢失。
渲染效果（GitHub 上）
ℹ️ Note
这是一个信息提示，用于补充说明。
💡 Tip
这是一个技巧提示，帮助读者更好完成任务。
⚠️ Warning
这是警告，操作可能导致问题。
🔴 Caution
这是危险提示，操作可能导致数据丢失。
[!NOTE]
蓝色，用于补充信息、额外说明，读者可以忽略不影响主流程
[!TIP]
绿色，有用的技巧或快捷方式，帮助用户更好地完成任务
[!IMPORTANT]
紫色，用户必须知道的重要信息
[!WARNING]
黄色，警告：有潜在问题，需要谨慎
[!CAUTION]
红色，严重警告：操作可能导致数据丢失或安全问题
WARNINGGitHub Alert 语法只在 GitHub.com 渲染（Issues、PR、README、Wiki），在其他 Markdown 渲染器（VS Code 预览、MkDocs 等）中会显示为普通引用块。如果需要跨平台兼容，MkDocs Material 有自己的 Admonition 语法，Docusaurus 也有 Admonition 组件。

水平分隔线（Thematic Breaks）

用三个或更多的 -（连字符）、*（星号）或 _（下划线）创建水平分隔线，对应 HTML 的 <hr> 元素：

多种等价写法
---
***
___
- - -
* * *
*  *  *
-----------
渲染效果（都生成一条水平线）

分隔线的语法规则

字符数量要求
至少 3 个相同字符（---、***、___），更多也可以（如 ----------）。字符之间可以有空格（- - - 有效，- - - 也有效）。
前导空格
分隔线前可以有 0-3 个空格缩进（4 个空格会被解析为代码块）。通常不加前导空格。
行内不能有其他字符
除了空格之外，分隔线所在行不能有其他字符，否则会被解析为普通文字。

最重要的陷阱：与 Setext 标题的歧义

这是 Markdown 中最常踩的坑之一：

# 这是 Setext H2 标题！不是段落 + 分隔线！
这行文字
---

# 这才是段落 + 分隔线（前面要有空行）
这行文字

---

# 也可以用三个星号避免歧义
这行文字

***
DANGER（重要陷阱）如果一行文字紧跟 ---，整个结构会被解析为 Setext H2 标题，而不是"文字 + 水平线"。这个歧义规则来自 CommonMark 规范：当有歧义时，优先解析为标题。规避方法：① 在分隔线前加空行；② 或改用 ***/___ 作为分隔线。

分隔线的使用场景

TIP技术文档中，分隔线不应该成为文档结构的主要组织方式。如果需要组织文档结构，应该使用标题（H2/H3）。分隔线只适用于"没有明确标题，但需要视觉分隔"的情况。

内嵌 HTML（Inline HTML）

Markdown 允许直接在文档中内嵌 HTML，这是 Markdown 务实设计哲学的体现——当 Markdown 语法不够用时，直接用 HTML 补充。

块级 HTML vs 内联 HTML

块级 HTML 元素
<div>、<table>、<pre>、<details> 等元素放在独立行时，其内部的 Markdown 语法不会被解析。这是块级 HTML 的一个陷阱。
内联 HTML 元素
<span>、<a>、<img>、<em>、<strong>、<mark> 等元素，可以穿插在 Markdown 文字中，周围的 Markdown 正常解析。
# 块级 HTML：内部 Markdown 不解析
<div class="notice">
**这里的星号不会变成加粗**
[这里的链接语法不会解析](url)
</div>

# 解决方法：在 div 的开闭标签之间留空行
<div class="notice">

**这里的 Markdown 可以解析了！**
[这个链接也可以](https://example.com)

</div>

# 内联 HTML：周围 Markdown 正常解析
这段有 <mark>高亮</mark> 的文字，以及 **加粗** 都正常。

HTML 注释

HTML 注释在 Markdown 渲染后不可见，常用于标注、TODO 和临时隐藏内容：

<!-- 这是一个注释，渲染后不可见 -->

<!-- TODO: 这里需要添加示例代码 -->

<!-- 以下内容暂时隐藏：
## 高级用法
...
-->

details/summary 折叠块

HTML5 的 <details>/<summary> 元素在 GitHub 中支持，可以创建可折叠的内容块：

<details>
<summary>点击展开：完整的安装步骤</summary>

## 详细安装步骤

1. 下载安装包...
2. 配置环境...

```bash
npm install -g my-tool
my-tool --version
```

</details>
点击展开：完整的安装步骤

详细安装步骤

  1. 下载安装包...
  2. 配置环境...
npm install -g my-tool
TIP（details 块的常见用途）在 GitHub README 中，<details> 块特别适合：① 折叠较长的安装步骤；② 折叠 FAQ 中的答案；③ 折叠"可选的高级配置"；④ 折叠贡献者列表；⑤ 长的输出示例（如日志）。让 README 更简洁，让感兴趣的用户展开查看详情。

图片对齐和排版

用 HTML 实现 Markdown 无法实现的图片排版：

# 居中对齐（用 align 属性，GitHub 支持）
<p align="center">
  <img src="logo.png" alt="Logo" width="200">
</p>

# 多图并排（用 table 或 div+float）
| 前 | 后 |
|:---:|:---:|
| <img src="before.png" width="200"> | <img src="after.png" width="200"> |

内嵌 HTML 的平台支持差异

平台HTML 支持程度特别说明
GitHub过滤危险标签后支持过滤 <script>/<style>/<iframe>；支持 <div>/<details>/<img> 等
VS Code 预览大部分支持（本地）本地文件预览权限较宽松
MkDocs支持可通过插件扩展
Docusaurus支持（JSX 模式）MDX 中可用 React 组件
Hugo默认禁用，需配置安全原因，需在配置中启用 unsafe: true
Obsidian部分支持不支持 <script>，其他大部分支持
Notion基本不支持Notion 使用自己的块编辑器，不直接渲染原始 HTML
WARNING如果你的 Markdown 文档需要在多个平台发布，应尽量避免依赖 HTML 特性（特别是 style 属性和复杂的 <div> 布局），优先使用标准 Markdown 语法保证最大兼容性。只有在当前平台明确支持且不需要跨平台迁移时，才大量使用 HTML。

HTML 与 Markdown 的边界

理解何时用 Markdown，何时用 HTML，是掌握这两者配合的关键：

优先用 Markdown

  • 标题、段落、列表
  • 代码块、内联代码
  • 链接、图片
  • 引用块
  • 表格（如果平台支持 GFM）

考虑用 HTML

  • 图片尺寸控制（<img width>）
  • 居中对齐（<p align>）
  • 折叠内容（<details>）
  • 复杂表格（合并单元格）
  • 文字高亮（<mark>）
  • 下标/上标（<sub>/<sup>）

小结

本章要点