ASP.NET Core 生产级开源文档系统

https://dotnet.github.io/docfx

区分两类形态：

1. 运行时动态服务（像 xxx那样：直接跑ASP.NET Core 程序，读取本地 md/xml，请求到来实时渲染，不需要预构建静态文件）
2. 静态站点生成器（CLI 工具，预先生成 html，再用 web 服务器托管）

xxx文档站属于第一类：动态运行时文档服务，不做预构建，磁盘放 markdown/xml，Kestrel 运行时解析渲染。

一、动态运行时（ASP.NET Core 直接跑，对标 xx的自研文档站）

1. Bark⭐（最贴近 xxx文档站形态）GitHub

• Github：melosso/bark
• 技术栈：ASP.NET Core + Markdig 解析 Markdown，运行时读取磁盘 md 文件，不用预编译，Docker 一键部署
• 特点：侧边导航、全文搜索、暗黑模式、版本文档、纯文件驱动，无数据库；直接挂载 docs 文件夹即可；生产真实部署案例不少。
• 和 xxx的相似点：不预生成静态 HTML，Web 服务启动后直接读磁盘 markdown，url 映射文档路径。
• 短板：定制 UI 需要改前端源码；没有原生 XML 注释自动提取 API 参考（xxx有自己的 xml 解析）。

2. Statiq Web（Wyam 下一代）

• 技术栈：ASP.NET Core，支持两种模式：①开发时动态运行渲染；②生产预构建输出静态文件
• 定位：.NET 生态最强的文档 / 站点引擎，Razor+Markdig 双解析；大量.NET 开源项目文档站在用。
• 优势：高度可扩展，可以同时做教程文档 + XML 注释 API 文档；可以写 C# 管道自定义导航树、自定义元数据；可以做成和 xxx几乎一模一样的动态文档服务。
• 短板：上手门槛偏高，配置代码多，不是开箱即用，需要自己搭布局。

3. Pennington DocSiteGitHub

• Github：usepennington/pennington
• ASP.NET Core，开发环境动态 serve，生产输出静态；内置文档站模板：侧边栏、搜索、代码高亮。
• 适合：想少量代码快速搭建文档门户，Razor 组件开箱可用。
• 短板：社区规模中等，国内案例少。

二、静态生成器（CLI 工具，预生成 HTML，.NET 生态占有率最高）

1. DocFX【.NET 生态占有率第一】

• 原微软官方工具，现在社区维护，C# 编写；微软 Learn 底层前身就是 DocFXGitHub。
• 两大能力：
  1. 读取 C# 项目 XML 注释自动生成 API 参考文档；
  2. 导入手写 Markdown 教程文档，合并为完整网站。
• 输出完整静态 HTML，丢 Nginx/IIS/Caddy 直接托管。
• 大量国内.NET 库在用（包含部分工业库），xxx的就是基于 DocFX 二次魔改。
• 短板：不是动态 web 服务，需要 CI/CD 构建；原生 UI 老旧，几乎所有人都会改模板。

2. MokaDocs（新一代 DocFX 竞品）GitHub

• dotnet tool 工具；读取 csproj 自动解析 XML 注释，同时支持 markdown 教程；
• 支持mokadocs serve本地动态预览；生产构建静态站；内置 Mermaid、代码块分组、暗黑模式。
• 相比 DocFXUI 现代化，但是社区体量还小。

三、不要混淆：API 接口文档工具（Swagger/NSwag）

Swashbuckle、NSwag，只用于 WebAPI 接口文档，不适合做产品教程、工业库长篇文档，和 xxx的 / Doc / 教程站不是一类东西GitHub。

四、横向对比，对标xxx

表格

五、选型建议（如果你要复刻 xxx的文档站模式）

1. 追求开箱即用，尽量少写代码：选 Bark。直接挂载 md 文件夹，动态运行，Docker 部署。缺点：API 参考需要自己额外处理。
2. 需要同时拥有【教程文档 + C# 代码 XML 注释 API 文档】，高度自定义，愿意写一点 C# 管道：选 Statiq Web，可以完全复现 xxx整套逻辑：磁盘 md/xml、动态路由、侧边导航树、代码高亮。
3. 只做 API 参考，教程少，接受预构建静态站：选 DocFX，工业.NET 库行业事实标准。

补充：xx文档站本质就是：自己手写一套轻量版 Statiq Web 逻辑，读取磁盘 xml/markdown，ASP.NET Core 运行时解析渲染，没有直接用开源项目，完全自研。