Migrate documentation from DocFX to VitePress with i18n support

Replace DocFX with VitePress for documentation generation, adding
English (default) and Chinese language support with automatic
language switcher. Update CI deploy-docs job to use Node.js/VitePress
build pipeline and add npm ecosystem to Dependabot.

Made-with: Cursor

Author: Hongwei-MB

.config/dotnet-tools.json

@@ -2,13 +2,6 @@
   "version": 1,
   "isRoot": true,
   "tools": {
-    "docfx": {
-      "version": "2.78.5",
-      "commands": [
-        "docfx"
-      ],
-      "rollForward": false
-    },
     "dotnet-reportgenerator-globaltool": {
       "version": "5.4.5",
       "commands": [

.github/dependabot.yml

@@ -9,6 +9,15 @@ updates:
         patterns: ["*"]
     open-pull-requests-limit: 10
 
+  - package-ecosystem: npm
+    directory: "/docs"
+    schedule:
+      interval: weekly
+    groups:
+      docs-deps:
+        patterns: ["*"]
+    open-pull-requests-limit: 5
+
   - package-ecosystem: nuget
     directory: "/"
     schedule:

.github/workflows/ci.yml

@@ -127,7 +127,7 @@ jobs:
             echo "| **Mode** | $MODE |"
             echo "| **Commit** | \`${SHA::8}\` |"
             echo "| **Expected Docs URL** | $DOCS_URL |"
-            echo "| **Docs Auto-Deploy** | Enable Pages (GitHub Actions) + add \`docs/docfx.json\` |"
+            echo "| **Docs Auto-Deploy** | Enable Pages (GitHub Actions) + add \`docs/package.json\` |"
           } >> "$GITHUB_STEP_SUMMARY"
 
       - name: Compute build matrix
@@ -502,17 +502,17 @@ jobs:
         with:
           ref: ${{ needs.resolve-version.outputs.sha }}
 
-      - name: Check for DocFX configuration
+      - name: Check for documentation configuration
         id: check-docs
         shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           HAS_DOCS="false"
-          if [ -f "docs/docfx.json" ]; then
+          if [ -f "docs/package.json" ]; then
             HAS_DOCS="true"
           else
-            echo "::notice::No docs/docfx.json found. Skipping documentation deployment."
+            echo "::notice::No docs/package.json found. Skipping documentation deployment."
           fi
 
           HAS_PAGES="$(gh api repos/${{ github.repository }} --jq '.has_pages' 2>/dev/null || echo "false")"
@@ -527,24 +527,28 @@ jobs:
             echo "should_deploy=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - uses: actions/setup-dotnet@v5
+      - uses: actions/setup-node@v4
         if: steps.check-docs.outputs.should_deploy == 'true'
         with:
-          global-json-file: global.json
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
 
-      - name: Restore .NET tools
+      - name: Install dependencies
         if: steps.check-docs.outputs.should_deploy == 'true'
-        run: dotnet tool restore
+        run: npm ci
+        working-directory: docs
 
       - name: Build documentation
         if: steps.check-docs.outputs.should_deploy == 'true'
-        run: dotnet docfx docs/docfx.json
+        run: npx vitepress build
+        working-directory: docs
 
       - name: Upload pages artifact
         if: steps.check-docs.outputs.should_deploy == 'true'
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/_site
+          path: docs/.vitepress/dist
 
       - name: Deploy to GitHub Pages
         if: steps.check-docs.outputs.should_deploy == 'true'

.gitignore

@@ -33,7 +33,8 @@ bld/
 [Oo]ut/
 [Ll]og/
 [Ll]ogs/
-docs/_site/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
 
 # Build results on 'Bin' directories
 **/[Bb]in/*

README.md

@@ -26,7 +26,7 @@ build-and-test ─── Matrix build (linux / windows / macos)
 release ────────── [requires approval] NuGet push + Git tag + GitHub Release
   |
   v
-deploy-docs ────── DocFX to GitHub Pages (optional)
+deploy-docs ────── VitePress to GitHub Pages (optional, i18n)
 ```
 
 On **pull requests**, only a fast linux build + test runs. On **main**, the full multi-platform pipeline kicks in.
@@ -43,7 +43,7 @@ On **pull requests**, only a fast linux build + test runs. On **main**, the full
 | **Version from Code** | `VersionPrefix` in `Directory.Build.props` is the single source of truth |
 | **Four-Part Release Tags** | `v0.2.0.42` format ensures unique tags per build |
 | **CodeQL Security** | Automated vulnerability scanning on every push and weekly |
-| **Graceful Degradation** | Missing NuGet key? Skipped. No DocFX config? Skipped. Nothing breaks. |
+| **Graceful Degradation** | Missing NuGet key? Skipped. No docs config? Skipped. Nothing breaks. |
 
 ---
 
@@ -85,7 +85,7 @@ The pipeline runs automatically. When `build-and-test` completes, go to **Action
 │   └── _build.csproj
 ├── src/                    # Your application code
 ├── tests/                  # Your test projects
-├── docs/                   # Guides (add docfx.json for auto-deploy)
+├── docs/                   # VitePress documentation (English + 中文)
 ├── Directory.Build.props   # Version + shared build properties
 └── global.json             # SDK version pinning
 ```
@@ -159,9 +159,11 @@ To serialize runs on the same branch (only one active at a time), set repository
 
 ## Documentation Deployment
 
+Documentation is built with [VitePress](https://vitepress.dev/) and supports English (default) and Chinese.
+
 To enable automatic documentation deployment to GitHub Pages:
 
-1. `docs/docfx.json` is included by default in this template
+1. `docs/package.json` is included by default in this template
 2. Enable GitHub Pages in **Settings > Pages > Source: GitHub Actions**
 3. The `deploy-docs` job automatically builds and deploys after each release
 4. Expected docs URL: `https://<owner>.github.io/<repo>/` (for this repo: `https://agibuild.github.io/dotnet.CI.template/`)

docs/.vitepress/config.ts

@@ -0,0 +1,48 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'dotnet.CI.template',
+  description: 'Production-ready .NET CI/CD template',
+
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        nav: [{ text: 'Guide', link: '/quick-start-release' }],
+        sidebar: [
+          {
+            text: 'Guide',
+            items: [
+              { text: 'Quick Start Release', link: '/quick-start-release' },
+              { text: 'GitHub Workflows Guide', link: '/github-workflows-guide' }
+            ]
+          }
+        ]
+      }
+    },
+    'zh-cn': {
+      label: '简体中文',
+      lang: 'zh-CN',
+      themeConfig: {
+        nav: [{ text: '指南', link: '/zh-cn/quick-start-release' }],
+        sidebar: [
+          {
+            text: '指南',
+            items: [
+              { text: '快速发版', link: '/zh-cn/quick-start-release' },
+              { text: 'Workflows 指南', link: '/zh-cn/github-workflows-guide' }
+            ]
+          }
+        ]
+      }
+    }
+  },
+
+  themeConfig: {
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/AGIBuild/dotnet.CI.template' }
+    ],
+    search: { provider: 'local' }
+  }
+})