docs: restructure site from CI-centric to product-centric layout

Move CI/CD and release guides into contributing/ section,
add product-oriented guide/, reference/ sections with i18n support.

Made-with: Cursor

Author: Hongwei-MB

docs/.vitepress/config.ts

@@ -1,41 +1,89 @@
 import { defineConfig } from 'vitepress'
 
 export default defineConfig({
-  title: 'dotnet.CI.template',
-  description: 'Production-ready .NET CI/CD template',
+  title: 'Dotnet.CI.Template',
+  description: 'A production-ready .NET project template with built-in CI/CD',
   base: '/dotnet.CI.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' }
-            ]
-          }
-        ]
+        nav: [
+          { text: 'Guide', link: '/guide/introduction' },
+          { text: 'Reference', link: '/reference/api' },
+          { text: 'Contributing', link: '/contributing/development' }
+        ],
+        sidebar: {
+          '/guide/': [
+            {
+              text: 'Guide',
+              items: [
+                { text: 'Introduction', link: '/guide/introduction' },
+                { text: 'Getting Started', link: '/guide/getting-started' }
+              ]
+            }
+          ],
+          '/reference/': [
+            {
+              text: 'Reference',
+              items: [
+                { text: 'API', link: '/reference/api' }
+              ]
+            }
+          ],
+          '/contributing/': [
+            {
+              text: 'Contributing',
+              items: [
+                { text: 'Development', link: '/contributing/development' },
+                { text: 'CI/CD', link: '/contributing/ci-cd' },
+                { text: 'Releasing', link: '/contributing/releasing' }
+              ]
+            }
+          ]
+        }
       }
     },
     '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' }
-            ]
-          }
-        ]
+        nav: [
+          { text: '指南', link: '/zh-cn/guide/introduction' },
+          { text: '参考', link: '/zh-cn/reference/api' },
+          { text: '开发贡献', link: '/zh-cn/contributing/development' }
+        ],
+        sidebar: {
+          '/zh-cn/guide/': [
+            {
+              text: '指南',
+              items: [
+                { text: '产品介绍', link: '/zh-cn/guide/introduction' },
+                { text: '快速开始', link: '/zh-cn/guide/getting-started' }
+              ]
+            }
+          ],
+          '/zh-cn/reference/': [
+            {
+              text: '参考',
+              items: [
+                { text: 'API', link: '/zh-cn/reference/api' }
+              ]
+            }
+          ],
+          '/zh-cn/contributing/': [
+            {
+              text: '开发贡献',
+              items: [
+                { text: '开发环境', link: '/zh-cn/contributing/development' },
+                { text: 'CI/CD 流程', link: '/zh-cn/contributing/ci-cd' },
+                { text: '发版指南', link: '/zh-cn/contributing/releasing' }
+              ]
+            }
+          ]
+        }
       }
     }
   },

docs/github-workflows-guide.md docs/contributing/ci-cd.mddocs/github-workflows-guide.md renamed to docs/contributing/ci-cd.md

@@ -1,10 +1,8 @@
-# GitHub Workflows Guide
+# CI/CD Pipeline
 
-The goal of these workflows is straightforward:
+The goal of this pipeline is straightforward:
 **Every commit gets quality feedback, releases are automated, artifacts are traceable and reproducible.**
 
-If you just created a repository from this template, think of it as a standard pipeline:
-
 ```text
 push / PR to main
   └─ CI and Release
@@ -18,7 +16,7 @@ push / PR to main + weekly
   └─ CodeQL (security scan)
 ```
 
-For a quick release walkthrough, see: [Quick Start Release](quick-start-release.md).
+For a quick release walkthrough, see: [Releasing](releasing.md).
 
 ---
 
@@ -75,22 +73,7 @@ For a quick release walkthrough, see: [Quick Start Release](quick-start-release.
 
 ---
 
-## 3) Quickest Path to Get Started (Recommended)
-
-1. Push a commit to `main`
-   Verify that both `CI and Release` and `CodeQL` are green.
-
-2. Go to Actions → find the workflow run → click **Review deployments**
-   Approve the `release` environment.
-
-3. Check the Releases page:
-   - A tag was created (e.g., `v0.2.0`)
-   - The GitHub Release contains platform installer zips
-   - A corresponding package version exists on NuGet.org (if `NUGET_API_KEY` is configured)
-
----
-
-## 4) Environment Configuration (Required)
+## 3) Environment Configuration
 
 ### `release` environment
 In GitHub repository Settings → Environments → create `release`:
@@ -101,15 +84,15 @@ In GitHub repository Settings → Environments → create `release`:
 The repository includes built-in VitePress documentation support. To enable documentation publishing:
 - Settings → Pages → Source: select GitHub Actions
 - The `github-pages` environment is created automatically
-- Expected documentation URL: `https://<owner>.github.io/<repo>/` (for this repo: `https://agibuild.github.io/dotnet.CI.template/`)
+- Expected documentation URL: `https://<owner>.github.io/<repo>/`
 - The `Resolve Version` summary displays this URL for quick access
 
 ### Secrets
 - `NUGET_API_KEY`: NuGet.org API key (configure at the repo or `release` environment level)
 
 ---
 
-## 5) Version Mechanism FAQ (Important)
+## 4) Version Mechanism FAQ
 
 ### Q1: Where does the version come from?
 The version comes from `VersionPrefix` in `Directory.Build.props`. CI does not accept manually input version parameters.
@@ -132,7 +115,7 @@ No. Each version can only be released once. If the tag `v{version}` already exis
 
 ---
 
-## 6) CLI Trigger (Optional)
+## 5) CLI Trigger (Optional)
 
 ```bash
 # Manually trigger CI and Release
@@ -141,7 +124,7 @@ gh workflow run ci.yml --ref main
 
 ---
 
-## 7) Common Troubleshooting (Check Here First)
+## 6) Troubleshooting
 
 - Tag already exists: This version was already published; bump `VersionPrefix` via PR
 - NuGet push failed: Verify that `NUGET_API_KEY` is configured
@@ -152,7 +135,7 @@ gh workflow run ci.yml --ref main
 
 ---
 
-## 8) Team Collaboration Tips
+## 7) Team Collaboration Tips
 
 - During daily development, just watch for green CI (Build + Test + CodeQL)
 - Release management is controlled through environment approval — no manual packaging or artifact transfer

docs/contributing/development.md

@@ -0,0 +1,88 @@
+# Development
+
+## Prerequisites
+
+| Tool | Version | Notes |
+|---|---|---|
+| .NET SDK | 10.0+ | Pinned in `global.json` (`rollForward: latestFeature`) |
+| Git | 2.x | |
+| Node.js | 18+ | Only needed for docs (`docs/package.json`) |
+
+## Clone & Build
+
+```bash
+git clone https://github.com/AGIBuild/dotnet.CI.template.git
+cd dotnet.CI.template
+
+./build.sh          # Linux / macOS
+build.ps1           # Windows
+```
+
+The default target is **Build** (Restore → Build).
+
+## NUKE Build Targets
+
+All build logic lives in `build/`. Workflows call these targets instead of raw `dotnet` commands.
+
+| Target | Depends On | Description |
+|---|---|---|
+| **Restore** | — | `dotnet restore` + tool restore |
+| **Build** | Restore | Build the solution |
+| **Test** | Build | Run tests with coverage (trx + Coverlet) |
+| **Pack** | Test | Pack NuGet packages (.nupkg + .snupkg) |
+| **Publish** | Restore | Publish the app for a given `--Runtime` |
+| **PackageApp** | Publish | Zip published output to `app-{runtime}.zip` |
+| **Format** | Restore | `dotnet format --verify-no-changes` |
+| **CoverageReport** | Test | Generate HTML + Cobertura coverage report |
+| **ShowVersion** | — | Print current `VersionPrefix` |
+| **UpdateVersion** | — | Bump patch or set `--VersionPrefix` explicitly |
+| **GenerateReleaseManifest** | Pack | Create `release-manifest.json` with SHA256 hashes |
+
+### Common Commands
+
+```bash
+./build.sh Test                                   # Build + Test
+./build.sh Pack                                   # Build + Test + Pack
+./build.sh Publish --Runtime linux-x64 --SelfContained  # Publish self-contained
+./build.sh CoverageReport                         # Generate coverage HTML
+./build.sh ShowVersion                            # Print version
+./build.sh UpdateVersion                          # Patch bump (e.g. 0.2.0 → 0.2.1)
+./build.sh UpdateVersion --VersionPrefix 1.0.0    # Set version explicitly
+```
+
+### Parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `--Configuration` | `Debug` (local) / `Release` (CI) | Build configuration |
+| `--VersionPrefix` | — | Version to set (used by `UpdateVersion`) |
+| `--VersionSuffix` | — | Prerelease suffix (e.g. `ci.42`) |
+| `--Runtime` | — | Target RID for `Publish` (e.g. `linux-x64`) |
+| `--SelfContained` | `false` | Produce self-contained output |
+
+### Artifacts
+
+All outputs go to `artifacts/`:
+
+```text
+artifacts/
+├── test-results/   # .trx files + coverage
+├── packages/       # .nupkg + .snupkg + release-manifest.json
+├── publish/        # dotnet publish output
+└── installers/     # app-{runtime}.zip
+```
+
+## Docs Development
+
+```bash
+cd docs
+npm install
+npm run docs:dev      # Local dev server at http://localhost:5173
+npm run docs:build    # Production build
+npm run docs:preview  # Preview production build
+```
+
+## Next Steps
+
+- [CI/CD Pipeline](ci-cd.md) — how the GitHub Actions workflow operates.
+- [Releasing](releasing.md) — how to ship a new version.

docs/quick-start-release.md docs/contributing/releasing.mddocs/quick-start-release.md renamed to docs/contributing/releasing.md

@@ -1,11 +1,11 @@
-# Quick Start: Release in 2 Minutes
+# Releasing
 
-Audience: New team members working with this repository for the first time.
+Audience: Team members shipping a new version.
 Goal: **Complete a standard Release quickly**.
 
 ---
 
-## 0) Prerequisites (30 seconds)
+## 0) Prerequisites
 
 - You have write access to the repository
 - `main` branch is up to date and CI is passing
@@ -39,19 +39,19 @@ After pushing to `main`:
 
 ---
 
-## 3) Success Criteria (30-second check)
+## 3) Success Criteria
 
 After a successful run, you should see:
 
 - A new tag (e.g., `v0.2.0`)
 - A new GitHub Release
 - Release assets including platform installer zips (`app-linux-x64.zip`, `app-win-x64.zip`, etc.) and the SBOM file
 - A corresponding package version on NuGet.org (if `NUGET_API_KEY` is configured)
-- If Pages is enabled: documentation at `https://agibuild.github.io/dotnet.CI.template/`
+- If Pages is enabled: documentation deployed automatically
 
 ---
 
-## 4) Version Management (Must Read)
+## 4) Version Management
 
 The version comes from `VersionPrefix` in `Directory.Build.props` — a pure 3-segment SemVer (e.g., `0.2.0`). A release is triggered only when this version differs from the latest git tag.
 
@@ -65,7 +65,7 @@ After committing the change to `main`, CI automatically builds and publishes wit
 
 ---
 
-## 5) Common Failure Troubleshooting
+## 5) Troubleshooting
 
 - `Tag already exists`: This version was already released; bump `VersionPrefix` and retry
 - `No .nupkg files found`: No artifacts from the packaging stage; check Build/Test/Pack logs
@@ -83,4 +83,4 @@ gh workflow run ci.yml --ref main
 
 ---
 
-For detailed information, see: [GitHub Workflows Guide](github-workflows-guide.md).
+For detailed pipeline information, see: [CI/CD Pipeline](ci-cd.md).

docs/guide/getting-started.md

@@ -0,0 +1,33 @@
+# Getting Started
+
+## Installation
+
+Add the NuGet package to your project:
+
+```bash
+dotnet add package Dotnet.CI.Template.Sample
+```
+
+## Usage
+
+```csharp
+using Dotnet.CI.Template.Sample;
+
+var calculator = new Calculator();
+
+var sum = calculator.Add(2, 3);       // 5
+var quotient = calculator.Divide(10, 2); // 5
+```
+
+## Using as a Template
+
+1. Click **Use this template** on the [GitHub repository](https://github.com/AGIBuild/dotnet.CI.template).
+2. Rename solution, projects, and namespaces to match your product.
+3. Replace the sample `Calculator` class with your own code.
+4. Update `Directory.Build.props` with your package metadata.
+5. Configure the `release` environment in GitHub Settings (see [Releasing](../contributing/releasing.md)).
+
+## Next Steps
+
+- [API Reference](../reference/api.md)
+- [Development Setup](../contributing/development.md)