TypeDoc导航配置：如何扁平化显示模块入口点

在TypeDoc文档生成工具中，模块入口点的导航显示方式是一个值得关注的配置细节。本文将深入探讨如何通过配置选项实现模块入口点的扁平化显示，避免不必要的层级结构。

问题背景

当使用TypeDoc为包含多个入口点的TypeScript项目生成文档时，开发者可能会遇到一个常见情况：模块名称中的斜杠(/)会被自动解析为导航层级结构。例如，模块名为"uneventful/extras"时，文档导航会将其显示为uneventful文件夹下的extras子项，而非直接显示完整模块名。

解决方案

TypeDoc提供了专门的配置选项来解决这一问题。在配置文件中设置navigation.includeFolders为false即可禁用基于斜杠的自动层级划分：

{
  "navigation": {
    "includeFolders": false
  }
}

启用此选项后，所有模块名称（包括包含斜杠的模块名）都会以完整形式直接显示在导航栏的根级别，不再被拆分为文件夹结构。

技术原理

这个配置选项的工作原理是改变了TypeDoc处理模块名称的方式：

1. 默认情况下（includeFolders: true），TypeDoc会将模块名中的每个斜杠视为路径分隔符，自动创建对应的文件夹层级结构
2. 当设置为false时，TypeDoc会将整个模块名视为一个不可分割的单元，直接显示在导航中

应用场景

这种配置特别适合以下情况：

• 项目采用多入口点设计，每个入口点有明确的完整模块名
• 开发者希望文档使用者能直接看到完整的导入路径
• 项目结构简单，不需要通过文件夹层级来组织文档

注意事项

1. 此配置会影响整个文档的导航结构，不仅是模块入口点
2. 对于大型复杂项目，禁用文件夹结构可能会降低导航的可读性
3. 该选项在TypeDoc 0.25.3之后的版本中可用

通过合理配置这一选项，开发者可以更灵活地控制文档的展示形式，使其更符合项目的实际结构和使用习惯。