dotnet-documentation-strategy

dotnet-documentation-strategy

.NET 项目的文档工具推荐：提供决策树，帮助选择 Starlight（基于 Astro，现代默认选择）、Docusaurus（基于 React，插件丰富）或 DocFX（由社区维护，原生集成 .NET XML 文档）。涵盖 MarkdownSnippets（用于从源文件中验证并引入代码）、所有平台的 Mermaid 渲染支持、工具之间的迁移路径，以及根据团队规模、项目类型和现有生态系统制定的项目背景驱动型推荐。

**版本假设：**Starlight v0.x+（Astro 4+）。Docusaurus v3.x（React 18+）。DocFX v2.x（由社区维护）。MarkdownSnippets 作为 dotnet tool（基准版本为 .NET 8.0+）。Mermaid v10+（GitHub、Starlight、Docusaurus 均可原生渲染）。

**范围边界：**此技能负责 .NET 项目的文档工具选择与配置——包括选择文档平台、初始设置和内容编写模式。将文档网站部署到 GitHub Pages 或其他托管服务的 CI 部署由 [skill:dotnet-gha-deploy] 负责。基于 XML 注释生成 API 参考文档由 [skill:dotnet-api-docs] 负责。

**范围之外：**文档网站的 CI/CD 部署流水线（GitHub Pages 工作流、基于 Docker 的部署）——请参阅 [skill:dotnet-gha-deploy]。API 文档生成的具体内容（DocFX API 参考设置、将 OpenAPI 用作文档）——请参阅 [skill:dotnet-api-docs]。XML 文档注释编写——请参阅 [skill:dotnet-xml-docs]。Mermaid 图表语法和 .NET 专用图表模式——请参阅 [skill:dotnet-mermaid-diagrams]。

交叉引用：[skill:dotnet-gha-deploy] 介绍文档网站部署流水线；[skill:dotnet-api-docs] 介绍 API 参考文档生成；[skill:dotnet-xml-docs] 介绍 XML 文档注释编写；[skill:dotnet-mermaid-diagrams] 介绍 .NET 专用 Mermaid 图表。

---

文档工具决策树

根据项目背景、团队能力和现有生态系统投入来选择文档工具。

快速决策矩阵

因素	Starlight	Docusaurus	DocFX
最适合	新项目、静态文档	React 团队、博客 + 文档	已有 XML 文档的 .NET 项目
学习曲线	低（Markdown + MDX）	中（React + MDX）	中（.NET 工具链）
内置搜索	是（Pagefind）	是（Algolia 插件）	是（Lunr.js）
文档版本管理	是（手动设置）	是（内置）	是（内置）
i18n 支持	是（内置）	是（内置）	有限
Mermaid 支持	原生（remark 插件）	原生（MDX 插件）	需要插件
从 XML 生成 API 参考文档	手动集成	手动集成	原生（docfx metadata）
托管	任意静态托管服务	任意静态托管服务	任意静态托管服务
构建速度	快（Astro）	中等（Webpack/Rspack）	中等（.NET 工具链）

决策流程图

Start: New documentation site for .NET project
  |
  +-- Do you have existing DocFX content?
  |     |
  |     +-- Yes --> Do you need XML doc API reference integration?
  |     |            |
  |     |            +-- Yes --> Stay with DocFX (lowest migration cost)
  |     |            |
  |     |            +-- No --> Migrate to Starlight (see Migration Paths below)
  |     |
  |     +-- No --> Is your team heavily invested in React?
  |                 |
  |                 +-- Yes --> Docusaurus (leverage React skills, plugin ecosystem)
  |                 |
  |                 +-- No --> Starlight (modern default, best DX)

项目背景因素

库与应用：

• 库项目可受益于 API 参考文档集成——DocFX 在这方面表现出色，可通过 docfx metadata 直接从 XML 注释生成 API 文档
• 应用项目通常需要指南、教程和架构文档——Starlight 或 Docusaurus 更适合
• 混合项目（库 + 应用文档）——可考虑使用 Starlight，并单独设置 API 参考文档部分，链接到 DocFX 生成的内容

团队规模：

• 独立开发者 / 小团队（1-3 人）：Starlight——配置最少，迭代快速
• 中型团队（4-10 人）：Starlight 或 Docusaurus——两者都有内置版本管理，能够很好地支持多位贡献者
• 大型团队（10 人以上）：Docusaurus——插件生态系统可支持复杂的多人协作工作流和自定义审查集成

现有生态系统：

• React 生态系统：Docusaurus 可自然集成现有 React 组件库和 Storybook
• 仅使用 .NET 工具链：DocFX 完全避免 JavaScript 构建依赖
• 多语言 / 现代技术栈：Starlight 适用于任何技术栈，只需掌握少量 JavaScript 知识

---

Starlight（基于 Astro）——现代默认选择

Starlight 是一个基于 Astro 的文档框架。对于新的 .NET 文档站点，它是推荐的默认选择，因为构建速度快、内置搜索（Pagefind）、支持 i18n，并原生支持 Mermaid。

初始设置

# Create a new Starlight project
npm create astro@latest -- --template starlight my-docs

cd my-docs
npm install
npm run dev

项目结构

my-docs/
  astro.config.mjs      # Starlight configuration
  src/
    content/
      docs/              # Markdown/MDX documentation pages
        index.mdx        # Landing page
        getting-started/
          installation.md
          quick-start.md
        guides/
          configuration.md
          architecture.md
        reference/
          api.md
          cli.md
    assets/              # Images, diagrams
  public/                # Static assets (favicon, robots.txt)

配置

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My .NET Library',
      social: {
        github: 'https://github.com/mycompany/my-library',
      },
      sidebar: [
        {
          label: 'Getting Started',
          items: [
            { label: 'Installation', slug: 'getting-started/installation' },
            { label: 'Quick Start', slug: 'getting-started/quick-start' },
          ],
        },
        {
          label: 'Guides',
          autogenerate: { directory: 'guides' },
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});

Starlight 中的 Mermaid 支持

# Install Mermaid remark plugin
npm install remark-mermaidjs

// astro.config.mjs
import remarkMermaid from 'remark-mermaidjs';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkMermaid],
  },
  integrations: [starlight({ /* ... */ })],
});

完成配置后，即可在任意 Markdown 文件中使用标准的 Mermaid 围栏代码块。有关 .NET 专用的图表模式，请参阅 [skill:dotnet-mermaid-diagrams]。

版本化文档

使用 @lorenzo_lewis/starlight-utils 插件实现版本下拉导航，这是 Starlight 版本化文档的推荐方式。

或者，在 astro.config.mjs 中使用基于目录的版本管理，并显式配置路由：

src/content/docs/
  v1/
    getting-started.md
    api-reference.md
  v2/
    getting-started.md
    api-reference.md

配置侧边栏，使其指向当前版本目录，并通过插件或自定义 Astro 组件添加版本选择器。

---

Docusaurus（基于 React）

Docusaurus 是由 Meta 维护的基于 React 的文档框架。对于已投入 React 生态的团队来说，这是一个不错的选择，它提供丰富的插件系统、内置博客和版本化文档。

初始设置

npx create-docusaurus@latest my-docs classic

cd my-docs
npm install
npm start

项目结构

my-docs/
  docusaurus.config.js   # Docusaurus configuration
  docs/                   # Markdown/MDX documentation
    intro.md
    getting-started/
      installation.md
    guides/
      configuration.md
  blog/                   # Optional blog posts
  src/
    components/           # Custom React components
    pages/                # Custom pages
  static/                 # Static assets
  sidebars.js             # Sidebar configuration

配置

// docusaurus.config.js
/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'My .NET Library',
  tagline: 'High-performance widgets for .NET',
  url: 'https://mycompany.github.io',
  baseUrl: '/my-library/',
  organizationName: 'mycompany',
  projectName: 'my-library',

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/mycompany/my-library/tree/main/docs/',
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],
};

module.exports = config;

Docusaurus 中的 Mermaid 支持

npm install @docusaurus/theme-mermaid

// docusaurus.config.js
const config = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
  // ...
};

版本化文档

Docusaurus 提供一流的版本管理支持：

# Snapshot current docs as a version
npx docusaurus docs:version 1.0

# Creates versioned_docs/version-1.0/ and versions.json

这会创建当前 docs/ 目录的快照。docs/ 目录仍表示尚未发布的“next”版本。

---

DocFX（由社区维护，原生支持 .NET）

DocFX 是一个原生支持 .NET 的文档生成器，可直接集成 XML 文档注释。Microsoft 于 2022 年 11 月停止官方支持，该项目现由社区维护。它在 .NET 生态中仍被广泛使用，尤其适用于需要大量 API 参考文档的项目。

初始设置

# Install DocFX as a .NET tool
dotnet tool install -g docfx

# Initialize a new DocFX project
docfx init

# Build the documentation
docfx build

# Serve locally
docfx serve _site

项目结构

docs/
  docfx.json              # DocFX configuration
  toc.yml                 # Table of contents
  index.md                # Landing page
  articles/               # Conceptual documentation
    getting-started.md
    configuration.md
  api/                    # Auto-generated API reference
    .gitignore            # Generated files excluded from source control
  images/                 # Static assets
  templates/              # Custom templates (optional)

配置

{
  "metadata": [
    {
      "src": [
        {
          "files": ["src/MyLibrary/MyLibrary.csproj"],
          "src": ".."
        }
      ],
      "dest": "api",
      "properties": {
        "TargetFramework": "net8.0"
      }
    }
  ],
  "build": {
    "content": [
      {
        "files": ["api/**.yml", "api/index.md"]
      },
      {
        "files": ["articles/**.md", "toc.yml", "*.md"]
      }
    ],
    "resource": [
      {
        "files": ["images/**"]
      }
    ],
    "dest": "_site",
    "globalMetadata": {
      "_appTitle": "My .NET Library",
      "_enableSearch": true
    }
  }
}

XML 文档集成

DocFX 的主要优势是可根据 XML 文档注释原生生成 API 参考文档：

# Generate API metadata from project XML docs
docfx metadata docfx.json

# This creates YAML files in the api/ directory
# representing all public types, methods, and properties

生成的 API 参考文档会通过 uid 交叉引用自动链接到概念性文章。有关编写 XML 文档注释的最佳实践，请参阅 [skill:dotnet-xml-docs]。

DocFX 中的 Mermaid 支持

DocFX 需要使用模板插件来渲染 Mermaid：

{
  "build": {
    "globalMetadata": {
      "_enableMermaid": true
    },
    "template": ["default", "modern"],
    "postProcessors": ["ExtractSearchIndex"]
  }
}

从 DocFX v2.75+ 开始，modern 模板已包含 Mermaid 支持。较早版本需要自定义模板扩展。请注意，_enableMermaid 是模板专用约定，并非 DocFX 官方文档所述的属性。对于 default 模板，请通过自定义模板扩展添加 Mermaid JavaScript 库。

---

MarkdownSnippets——经验证的代码引入

MarkdownSnippets 是一个 dotnet tool，可将实际源文件中经验证的代码片段引入 Markdown 文档。它让文档与可编译的源代码保持同步，从而避免代码示例过时。

安装

# Install as a local dotnet tool
dotnet new tool-manifest
dotnet tool install MarkdownSnippets.Tool

# Or install globally
dotnet tool install -g MarkdownSnippets.Tool

用法

1. 在源文件中使用 #region 指令标记代码区域：

// src/MyLibrary/WidgetService.cs
public class WidgetService
{
    #region CreateWidget
    public async Task<Widget> CreateWidgetAsync(string name, CancellationToken ct = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(name);

        var widget = new Widget { Name = name, CreatedAt = DateTimeOffset.UtcNow };
        await _repository.AddAsync(widget, ct);
        return widget;
    }
    #endregion
}

2. 在 Markdown 中引用代码片段：

## Creating a Widget

To create a widget, use the `CreateWidgetAsync` method:

3. 运行 MarkdownSnippets 注入代码：

dotnet tool run mdsnippets

这会将代码片段占位符替换为源文件中的实际代码，使文档与实现保持同步。

配置

// mdsnippets.json (project root)
{
  "Convention": "InPlaceOverwrite",
  "ReadOnly": false,
  "LinkFormat": "GitHub",
  "UrlPrefix": "https://github.com/mycompany/my-library/blob/main",
  "TocExcludes": ["**/obj/**", "**/bin/**"],
  "ExcludeDirectories": ["node_modules", ".git"]
}

与文档平台集成

MarkdownSnippets 适用于这三个文档平台，因为它会在平台构建步骤之前处理标准 Markdown 文件：

# In your build script or CI pipeline:
dotnet tool run mdsnippets    # 1. Inject verified snippets
npm run build                 # 2. Build Starlight/Docusaurus site

# For DocFX:
dotnet tool run mdsnippets    # 1. Inject verified snippets
docfx build                   # 2. Build DocFX site

---

跨平台 Mermaid 渲染

所有三个推荐的文档平台都支持 Mermaid 图表，GitHub 也能在 Markdown 文件中原生渲染 Mermaid。

平台	Mermaid 支持	所需配置
GitHub	原生支持	无——使用带有 mermaid 语言标识符的围栏代码块
Starlight	插件	remark-mermaidjs npm 包
Docusaurus	插件	@docusaurus/theme-mermaid + 配置标志
DocFX	模板	modern 模板或自定义模板扩展

所有平台都使用带有 mermaid 语言标识符的标准围栏代码块：

```mermaid
graph LR
    A[Client] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
```

参见 [skill:dotnet-mermaid-diagrams]，了解 .NET 专用图表类型（C4 架构、异步模式、EF Core 模型、DI 图）。

---

迁移路径

DocFX 迁移到 Starlight

对于正在更新文档的 .NET 项目，DocFX 迁移到 Starlight 是最常见的路径。

内容迁移：

1. 将 articles/ Markdown 文件复制到 src/content/docs/
2. 将 toc.yml 条目转换为 astro.config.mjs 中的 Starlight 侧边栏配置
3. 将 DocFX 专用元数据 YAML 标头替换为 Starlight frontmatter
4. 将 xref 交叉引用转换为标准 Markdown 链接
5. 将 DocFX 专用的 > [!NOTE] / > [!WARNING] 提示语法替换为 Starlight <Aside> 组件（或保留与 GitHub 兼容的块引用语法）

API 参考迁移：

• DocFX docfx metadata 的输出（YAML 文件）没有直接对应的 Starlight 功能
• 方案 A：继续运行 docfx metadata，并将 API 参考托管为独立子站点
• 方案 B：使用 TypeDoc 风格的 API 提取工具，并将内容转换为 Markdown 页面
• 方案 C：链接到托管在独立 URL 上的 API 参考

检查清单：

# Find all DocFX-specific syntax to convert
grep -rn "xref:" articles/                # Cross-references
grep -rn "\[!NOTE\]" articles/            # Callout syntax
grep -rn "\[!WARNING\]" articles/         # Callout syntax
grep -rn "^\s*uid:" articles/             # UID metadata

Docusaurus 迁移到 Starlight

内容迁移：

1. 将 docs/ Markdown 文件复制到 src/content/docs/
2. 将 sidebars.js 转换为 Starlight 侧边栏配置
3. 将 Docusaurus 专用 MDX 组件（<Tabs>、<TabItem>）替换为 Starlight 对应组件
4. 将 docusaurus.config.js 导航配置转换为 Starlight 配置
5. 如果 MDX 中使用了自定义 React 组件，则进行迁移（Starlight 支持 Astro 组件，并可通过 @astrojs/react 有限支持 React）

博客迁移：

• Starlight 没有内置博客——可使用社区插件 starlight-blog，或维护独立的 Astro 博客部分

---

Agent 注意事项

1. 将 Starlight 作为现代默认选项推荐——除非项目已有大量集成 XML 文档的 DocFX 站点，或团队深度投入 React（Docusaurus）。对于不需要 XML 文档 API 参考的新项目，不要推荐 DocFX。

2. 自 2022 年 11 月起，DocFX 由社区维护——Microsoft 已将仓库移交给社区。它仍在积极维护且广泛使用，但新项目应优先评估 Starlight 或 Docusaurus。

3. MarkdownSnippets 在文档平台构建之前运行——这是一个预处理步骤，会原地修改 Markdown 文件。始终在运行 npm run build（Starlight/Docusaurus）或 docfx build（DocFX）之前运行 dotnet tool run mdsnippets。

4. 不要生成 CI 部署 YAML——文档站点部署工作流属于 [skill:dotnet-gha-deploy]。此技能仅涵盖工具选择和本地编写环境的设置。

5. 不要生成 API 参考配置——DocFX API 参考设置、将 OpenAPI 用作文档的模式以及文档与代码同步均属于 [skill:dotnet-api-docs]。此技能帮助选择平台，而非配置 API 参考生成。

6. Mermaid 围栏代码块在 GitHub、Starlight 和 Docusaurus 中的工作方式完全相同——在所有地方使用相同的 mermaid 语言标识符。只有 DocFX 需要额外的模板配置。

7. MarkdownSnippets 的 #region 名称在整个解决方案中必须唯一——重复的区域名称会导致代码片段解析不明确。使用 CreateWidgetAsync 这类描述性名称，而不要使用 Example1 这类通用名称。

8. Starlight 的版本管理基于目录，而非命令——与 Docusaurus（npx docusaurus docs:version）不同，Starlight 使用目录结构或社区插件进行版本管理。不要为 Starlight 项目建议 Docusaurus 版本管理命令。