深入理解Dumi文档工具中Demo标题与侧边栏TOC的关联机制

在使用Dumi文档工具时，开发者可能会遇到一个有趣的现象：代码块中通过JSDoc注释定义的title属性会被自动渲染到侧边栏的目录(TOC)结构中。这一设计实际上体现了Dumi对文档结构自动化的巧妙处理，而非一个系统缺陷。

现象解析

当开发者在Markdown文件中嵌入代码示例时，通常会使用类似如下的JSDoc注释来定义Demo的元信息：

/**
* title: 读取状态
* description: 通过store.state.firstName直接读取状态
*/

按照预期，这些元信息应该仅用于控制Demo组件的展示方式。然而实际上，title属性会被Dumi同时用于两个地方：

1. 作为Demo组件的标题显示在页面内容区域
2. 作为目录项出现在侧边栏的TOC结构中

设计原理

这一行为源于Dumi对文档结构的自动化处理机制。Dumi将整个文档页面视为一个层次结构，其中包含：

1. 主标题(H1)
2. 子标题(H2-H6)
3. 代码示例(Demo)

Dumi默认将Demo标题视为文档结构的一部分，与常规标题具有同等地位，因此会将其纳入TOC系统。这种设计有助于：

• 保持文档结构的完整性
• 提供更丰富的导航选项
• 增强文档的可浏览性

自定义配置方案

如果开发者不希望Demo标题出现在TOC中，可以通过以下两种方式调整：

方法一：修改tocDepth配置

在文档的frontmatter中增加tocDepth配置：

---
tocDepth: 2
---

这将限制TOC只显示到二级标题(H2)，而Demo标题属于更深层级，因此不会被展示。

方法二：调整Demo的元数据

另一种方式是重新组织Demo的元数据，将关键信息放在description而非title中：

/**
* description: 读取状态 - 通过store.state.firstName直接读取状态
*/

这种方式下，Demo将使用默认标题，不会影响TOC结构。

最佳实践建议

1. 对于重要的、需要突出展示的Demo，建议保留title属性，利用TOC增强可发现性
2. 对于辅助性的、次要的Demo示例，可以使用description-only的方式
3. 合理规划文档结构，使TOC既能提供有效导航，又不会过于冗长
4. 在大型文档项目中，统一团队对Demo标题的使用规范

通过理解这些机制，开发者可以更有效地利用Dumi的自动化功能，创建结构清晰、易于导航的技术文档。