用途:为 .NET 项目选择与配置文档工具,给出 Starlight(Astro)、Docusaurus(React)、DocFX(.NET 原生)的决策树、初始搭建与内容编写模式,并说明工具间迁移路径。
主要能力:提供快速决策矩阵与流程图,按项目类型(库/应用/混合)、团队规模(1-3、4-10、10+)和现有生态(React、纯 .NET、多语言)给出推荐;覆盖三者的搜索、版本化文档、i18n、Mermaid 支持与构建速度对比。
使用方式:Starlight 用 npm create astro@latest -- --template starlight my-docs 创建,Mermaid 需安装 remark-mermaidjs;Docusaurus 用 npx create-docusaurus@latest my-docs classic,Mermaid 需 @docusaurus/theme-mermaid,版本化用 npx docusaurus docs:version 1.0;DocFX 用 dotnet tool install -g docfx,再 docfx init、docfx build、docfx serve _site,API 元数据用 docfx metadata docfx.json。MarkdownSnippets 通过 dotnet tool install MarkdownSnippets.Tool 安装,在源码中用 #region 标记,Markdown 中用 snippet 占位,运行 dotnet tool run mdsnippets 注入。
适用场景:新建 .NET 文档站、从 DocFX 迁移到 Starlight、React 团队选 Docusaurus、需要 XML 注释生成 API 参考的库项目。
限制:DocFX 自 2022 年 11 月起由社区维护;Starlight 版本化需插件或目录方案;DocFX 的 Mermaid 依赖模板,_enableMermaid 非官方属性;API 参考从 XML 生成无直接 Starlight 等价方案。CI 部署、API 文档生成细节、XML 注释编写与 Mermaid 语法不在本技能范围内。