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 が適しています
• ハイブリッド（ライブラリとアプリのドキュメント）では、DocFX で生成したコンテンツにリンクする独立した API リファレンスセクションを設けた Starlight を検討してください

チーム規模：

• 個人／小規模チーム（1～3 人）：Starlight — 構成が最小限で、素早く反復できます
• 中規模チーム（4～10 人）：Starlight または Docusaurus — どちらも組み込みのバージョン管理機能で複数のコントリビューターに対応できます
• 大規模チーム（10 人以上）：Docusaurus — プラグインのエコシステムが、複雑な複数執筆者のワークフローやカスタムレビュー統合に対応します

既存のエコシステム：

• React エコシステム：Docusaurus は既存の React コンポーネントライブラリや Storybook と自然に統合できます
• .NET のみのツールチェーン：DocFX なら JavaScript のビルド依存関係を完全に回避できます
• 複数言語／モダンな環境：Starlight はあらゆる技術スタックで利用でき、必要な JavaScript の知識も最小限です

---

Starlight（Astro ベース）――モダンなデフォルト

Starlight は Astro ベースのドキュメントフレームワークです。ビルド時間が短く、検索（Pagefind）、i18n、Mermaid のネイティブサポートが組み込まれているため、新しい .NET ドキュメントサイトにはデフォルトで推奨されます。

初期セットアップ

# 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/ ディレクトリは、リリース前の「次期」バージョンを引き続き表します。

---

DocFX（コミュニティ保守、.NET ネイティブ）

DocFX は、XML ドキュメントコメントと直接連携する .NET ネイティブのドキュメント生成ツールです。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"]
  }
}

modern テンプレートには、DocFX v2.75 以降、Mermaid サポートが含まれています。それより前のバージョンでは、カスタムテンプレート拡張機能が必要です。なお、_enableMermaid はテンプレート固有の慣例であり、DocFX の公式ドキュメントに記載されたプロパティではありません。default テンプレートでは、カスタムテンプレート拡張機能を介して Mermaid JavaScript ライブラリを追加してください。

---

MarkdownSnippets――検証済みコードの挿入

MarkdownSnippets は、実際のソースファイルから検証済みのコードスニペットを Markdown ドキュメントに挿入する dotnet tool です。コンパイル可能なソースコードとドキュメントを同期させることで、古くなったコード例をなくせます。

インストール

# 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 ファイルを処理するため、3 つのドキュメントプラットフォームすべてで利用できます。

# 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 のレンダリング

おすすめのドキュメントプラットフォームは3つとも 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]
```

.NET 固有の図の種類（C4 アーキテクチャ、非同期パターン、EF Core モデル、DI グラフ）については、[skill:dotnet-mermaid-diagrams] を参照してください。

---

移行パス

DocFX から Starlight へ

DocFX から Starlight への移行は、ドキュメントを最新化する .NET プロジェクトで最もよくある移行パスです。

コンテンツの移行：

1. articles/ の Markdown ファイルを src/content/docs/ にコピーします
2. toc.yml の項目を astro.config.mjs の Starlight サイドバー設定に変換します
3. DocFX 固有のメタデータ YAML ヘッダーを Starlight のフロントマターに置き換えます
4. xref による相互参照を標準の Markdown リンクに変換します
5. > [!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 ブログセクションを運用してください

---

エージェントが注意すべき点

1. 最新の標準として Starlight を推奨します -- 既存の DocFX サイトに XML ドキュメントとの緊密な統合がある場合、またはチームが React（Docusaurus）に深く投資している場合を除きます。XML ドキュメントの API リファレンスが必要でない新規プロジェクトには、DocFX を推奨しないでください。

2. DocFX は 2022 年 11 月以降、コミュニティによって保守されています -- Microsoft はリポジトリをコミュニティに移管しました。現在も活発に保守され、広く使われていますが、新規プロジェクトではまず Starlight または Docusaurus を検討してください。

3. MarkdownSnippets はドキュメントプラットフォームのビルド前に実行します -- Markdown ファイルをその場で変更する前処理ステップです。必ず dotnet tool run mdsnippets を、npm run build（Starlight／Docusaurus）または docfx build（DocFX）の前に実行してください。

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 名はソリューション全体で一意にしてください -- リージョン名が重複すると、スニペットの解決が曖昧になります。Example1 のような汎用的な名前ではなく、CreateWidgetAsync のような説明的な名前を使ってください。

8. Starlight のバージョン管理はコマンドではなくディレクトリベースです -- Docusaurus（npx docusaurus docs:version）とは異なり、Starlight ではバージョン管理にディレクトリ構造またはコミュニティ製プラグインを使います。Starlight プロジェクトに Docusaurus のバージョン管理コマンドを提案しないでください。