Skip to content

Commit e3b220f

Browse files
committed
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
1 parent 84d3c9a commit e3b220f

16 files changed

Lines changed: 2989 additions & 194 deletions

.config/dotnet-tools.json

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,6 @@
22
"version": 1,
33
"isRoot": true,
44
"tools": {
5-
"docfx": {
6-
"version": "2.78.5",
7-
"commands": [
8-
"docfx"
9-
],
10-
"rollForward": false
11-
},
125
"dotnet-reportgenerator-globaltool": {
136
"version": "5.4.5",
147
"commands": [

.github/dependabot.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,15 @@ updates:
99
patterns: ["*"]
1010
open-pull-requests-limit: 10
1111

12+
- package-ecosystem: npm
13+
directory: "/docs"
14+
schedule:
15+
interval: weekly
16+
groups:
17+
docs-deps:
18+
patterns: ["*"]
19+
open-pull-requests-limit: 5
20+
1221
- package-ecosystem: nuget
1322
directory: "/"
1423
schedule:

.github/workflows/ci.yml

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ jobs:
127127
echo "| **Mode** | $MODE |"
128128
echo "| **Commit** | \`${SHA::8}\` |"
129129
echo "| **Expected Docs URL** | $DOCS_URL |"
130-
echo "| **Docs Auto-Deploy** | Enable Pages (GitHub Actions) + add \`docs/docfx.json\` |"
130+
echo "| **Docs Auto-Deploy** | Enable Pages (GitHub Actions) + add \`docs/package.json\` |"
131131
} >> "$GITHUB_STEP_SUMMARY"
132132
133133
- name: Compute build matrix
@@ -502,17 +502,17 @@ jobs:
502502
with:
503503
ref: ${{ needs.resolve-version.outputs.sha }}
504504

505-
- name: Check for DocFX configuration
505+
- name: Check for documentation configuration
506506
id: check-docs
507507
shell: bash
508508
env:
509509
GH_TOKEN: ${{ github.token }}
510510
run: |
511511
HAS_DOCS="false"
512-
if [ -f "docs/docfx.json" ]; then
512+
if [ -f "docs/package.json" ]; then
513513
HAS_DOCS="true"
514514
else
515-
echo "::notice::No docs/docfx.json found. Skipping documentation deployment."
515+
echo "::notice::No docs/package.json found. Skipping documentation deployment."
516516
fi
517517
518518
HAS_PAGES="$(gh api repos/${{ github.repository }} --jq '.has_pages' 2>/dev/null || echo "false")"
@@ -527,24 +527,28 @@ jobs:
527527
echo "should_deploy=false" >> "$GITHUB_OUTPUT"
528528
fi
529529
530-
- uses: actions/setup-dotnet@v5
530+
- uses: actions/setup-node@v4
531531
if: steps.check-docs.outputs.should_deploy == 'true'
532532
with:
533-
global-json-file: global.json
533+
node-version: 22
534+
cache: npm
535+
cache-dependency-path: docs/package-lock.json
534536

535-
- name: Restore .NET tools
537+
- name: Install dependencies
536538
if: steps.check-docs.outputs.should_deploy == 'true'
537-
run: dotnet tool restore
539+
run: npm ci
540+
working-directory: docs
538541

539542
- name: Build documentation
540543
if: steps.check-docs.outputs.should_deploy == 'true'
541-
run: dotnet docfx docs/docfx.json
544+
run: npx vitepress build
545+
working-directory: docs
542546

543547
- name: Upload pages artifact
544548
if: steps.check-docs.outputs.should_deploy == 'true'
545549
uses: actions/upload-pages-artifact@v3
546550
with:
547-
path: docs/_site
551+
path: docs/.vitepress/dist
548552

549553
- name: Deploy to GitHub Pages
550554
if: steps.check-docs.outputs.should_deploy == 'true'

.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@ bld/
3333
[Oo]ut/
3434
[Ll]og/
3535
[Ll]ogs/
36-
docs/_site/
36+
docs/.vitepress/dist/
37+
docs/.vitepress/cache/
3738

3839
# Build results on 'Bin' directories
3940
**/[Bb]in/*

README.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ build-and-test ─── Matrix build (linux / windows / macos)
2626
release ────────── [requires approval] NuGet push + Git tag + GitHub Release
2727
|
2828
v
29-
deploy-docs ────── DocFX to GitHub Pages (optional)
29+
deploy-docs ────── VitePress to GitHub Pages (optional, i18n)
3030
```
3131

3232
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
4343
| **Version from Code** | `VersionPrefix` in `Directory.Build.props` is the single source of truth |
4444
| **Four-Part Release Tags** | `v0.2.0.42` format ensures unique tags per build |
4545
| **CodeQL Security** | Automated vulnerability scanning on every push and weekly |
46-
| **Graceful Degradation** | Missing NuGet key? Skipped. No DocFX config? Skipped. Nothing breaks. |
46+
| **Graceful Degradation** | Missing NuGet key? Skipped. No docs config? Skipped. Nothing breaks. |
4747

4848
---
4949

@@ -85,7 +85,7 @@ The pipeline runs automatically. When `build-and-test` completes, go to **Action
8585
│ └── _build.csproj
8686
├── src/ # Your application code
8787
├── tests/ # Your test projects
88-
├── docs/ # Guides (add docfx.json for auto-deploy)
88+
├── docs/ # VitePress documentation (English + 中文)
8989
├── Directory.Build.props # Version + shared build properties
9090
└── global.json # SDK version pinning
9191
```
@@ -159,9 +159,11 @@ To serialize runs on the same branch (only one active at a time), set repository
159159

160160
## Documentation Deployment
161161

162+
Documentation is built with [VitePress](https://vitepress.dev/) and supports English (default) and Chinese.
163+
162164
To enable automatic documentation deployment to GitHub Pages:
163165

164-
1. `docs/docfx.json` is included by default in this template
166+
1. `docs/package.json` is included by default in this template
165167
2. Enable GitHub Pages in **Settings > Pages > Source: GitHub Actions**
166168
3. The `deploy-docs` job automatically builds and deploys after each release
167169
4. Expected docs URL: `https://<owner>.github.io/<repo>/` (for this repo: `https://agibuild.github.io/dotnet.CI.template/`)

docs/.vitepress/config.ts

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
export default defineConfig({
4+
title: 'dotnet.CI.template',
5+
description: 'Production-ready .NET CI/CD template',
6+
7+
locales: {
8+
root: {
9+
label: 'English',
10+
lang: 'en',
11+
themeConfig: {
12+
nav: [{ text: 'Guide', link: '/quick-start-release' }],
13+
sidebar: [
14+
{
15+
text: 'Guide',
16+
items: [
17+
{ text: 'Quick Start Release', link: '/quick-start-release' },
18+
{ text: 'GitHub Workflows Guide', link: '/github-workflows-guide' }
19+
]
20+
}
21+
]
22+
}
23+
},
24+
'zh-cn': {
25+
label: '简体中文',
26+
lang: 'zh-CN',
27+
themeConfig: {
28+
nav: [{ text: '指南', link: '/zh-cn/quick-start-release' }],
29+
sidebar: [
30+
{
31+
text: '指南',
32+
items: [
33+
{ text: '快速发版', link: '/zh-cn/quick-start-release' },
34+
{ text: 'Workflows 指南', link: '/zh-cn/github-workflows-guide' }
35+
]
36+
}
37+
]
38+
}
39+
}
40+
},
41+
42+
themeConfig: {
43+
socialLinks: [
44+
{ icon: 'github', link: 'https://github.com/AGIBuild/dotnet.CI.template' }
45+
],
46+
search: { provider: 'local' }
47+
}
48+
})

docs/docfx.json

Lines changed: 0 additions & 34 deletions
This file was deleted.

0 commit comments

Comments
 (0)