Docusaurus 文档标题中的 HTML 标签处理机制解析

在使用 Docusaurus 构建文档网站时，开发者可能会遇到一个有趣的现象：文档正文中的标题能够正确渲染 HTML 标签，但在侧边栏和面包屑导航中，这些标签却会被转义显示。这种现象实际上反映了 Docusaurus 对文档标题在不同上下文中处理的差异。

现象描述

当我们在 Markdown 文件中使用包含 HTML 标签的标题时，例如：

# 教程 <i>介绍</i> \<带括号的内容\>

在文档正文区域，这个标题会按照预期渲染，HTML 标签会被解析执行，"介绍"二字会以斜体显示。然而，在侧边栏导航和面包屑导航中，同样的标题会显示为转义后的文本：

教程 \<i\>介绍\</i\> \\\<带括号的内容\\\>

技术原理

这种现象源于 Docusaurus 对标题在不同场景下的不同处理策略：

1. 正文渲染：在文档内容区域，Docusaurus 使用完整的 Markdown/MDX 解析器处理标题，因此 HTML 标签能够被正确解析和渲染。

2. 导航系统渲染：在侧边栏和面包屑导航中，出于性能和安全考虑，Docusaurus 会对标题进行字符串化处理。这个过程会将所有特殊字符（包括 HTML 标签）进行转义，确保它们以纯文本形式显示。

解决方案

如果开发者希望在导航系统中显示不同的标题文本，Docusaurus 提供了专门的解决方案：

1. 使用 sidebar_label 元数据：在文档的 front matter 中，可以指定一个专门用于侧边栏显示的标题：

---
sidebar_label: "教程介绍（带括号的内容）"
---

# 教程 <i>介绍</i> \<带括号的内容\>

2. 保持简洁的标题：最佳实践是避免在文档标题中使用复杂的 HTML 标签，保持标题简洁明了。需要特殊样式的内容可以放在文档正文中。

设计考量

Docusaurus 的这种设计有几个合理的考虑：

1. 安全性：导航系统通常不需要复杂的 HTML 渲染，避免解析 HTML 可以减少潜在的 XSS 攻击面。

2. 一致性：确保导航系统中的标题显示风格统一，不受个别文档中 HTML 样式的影响。

3. 性能：字符串化的标题处理起来更高效，特别是在需要频繁渲染导航结构的场景下。

总结

理解 Docusaurus 对文档标题的不同处理方式，有助于开发者更好地组织文档结构。虽然正文中可以使用丰富的 HTML 标签来增强表现力，但在导航系统中，建议使用简洁的纯文本标题，或者通过 sidebar_label 专门指定导航显示文本。这种分离关注点的设计既保证了灵活性，又确保了系统的稳定性和一致性。