TypeDoc中@includeCode标签对.mts文件区域引用的支持问题解析

TypeDoc作为一款优秀的TypeScript文档生成工具，其@includeCode标签功能允许开发者在文档中直接引用源代码片段。然而，近期发现该功能在处理.mts扩展名的TypeScript文件时存在兼容性问题。

问题背景

TypeScript从4.5版本开始引入了.mts扩展名，用于表示ES模块格式的TypeScript文件。这类文件与传统的.ts文件在语法上完全一致，只是模块系统不同。但在TypeDoc中，当开发者尝试使用@includeCode标签引用.mts文件中的代码区域时，系统会报错提示不支持该文件扩展名的区域引用功能。

技术分析

问题的根源在于TypeDoc的IncludePlugin插件中，区域标签的正则表达式匹配规则是按文件扩展名分类存储的。当前的实现只预置了.ts文件的匹配规则，没有包含.mts文件的配置。

在底层实现上，TypeDoc使用正则表达式来识别源代码中的区域标记（如//#region和//#endregion）。这些正则表达式被存储在regionTagREsByExt这个按扩展名分类的对象中。由于.mts未被包含在内，导致系统无法正确处理这类文件中的区域标记。

解决方案

要解决这个问题，需要从两个层面进行修改：

1. 区域标记支持：在IncludePlugin中为.mts文件添加与.ts相同的区域标记识别规则。这可以通过简单的配置映射实现：

   regionTagREsByExt["mts"] = regionTagREsByExt["ts"];
   

2. 语法高亮支持：TypeDoc使用highlight.js进行代码高亮，需要确保它能正确识别.mts文件的语法。这需要在highlighter.tsx中添加对应的语言别名配置，将.mts映射到TypeScript的高亮规则。

实现建议

对于想要临时解决此问题的开发者，可以通过monkey patch的方式在项目初始化时添加这些配置。但从长远来看，建议直接修改TypeDoc源码，因为.mts作为TypeScript的标准扩展名，理应获得与.ts相同的支持。

TypeScript生态中，类似的文件扩展名还有.cts（CommonJS模块的TypeScript文件），在实现解决方案时也应一并考虑对这些扩展名的支持，确保功能的完整性。

总结

这个问题反映了工具链对新语言特性支持的滞后性。随着TypeScript模块系统的演进，工具开发者需要及时跟进这些变化，确保对标准特性的全面支持。对于文档工具而言，保持与语言特性的同步尤为重要，因为这直接影响到开发者体验和文档质量。