Enable DocFX docs deployment with default project setup

- Add default DocFX config, home page, and TOC under docs/
- Add local tool manifest with docfx tool for workflow restore
- Show fixed expected docs URL in workflow summary
- Align build tool-manifest path and docs guidance in README/guide
- Ignore generated docs/_site output

Made-with: Cursor

Author: Hongwei-MB

.github/workflows/ci.yml

@@ -183,7 +183,7 @@ jobs:
       - uses: actions/cache@v5
         with:
           path: ~/.nuget/packages
-          key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj', 'global.json', '.config/dotnet-tools.json') }}
+          key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj', 'global.json', 'dotnet-tools.json') }}
           restore-keys: ${{ runner.os }}-nuget-
 
       - name: Install .NET workloads

.gitignore

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

README.md

@@ -148,9 +148,9 @@ env:
 
 To enable automatic documentation deployment to GitHub Pages:
 
-1. Add a `docs/docfx.json` configuration file
+1. `docs/docfx.json` is included by default in this template
 2. Enable GitHub Pages in **Settings > Pages > Source: GitHub Actions**
-3. The `deploy-docs` job will automatically build and deploy after each release
+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/`)
 
 The `Resolve Version` job summary always shows this expected docs URL, even when docs deployment is skipped.

build/BuildTask.Parameters.cs

@@ -35,6 +35,6 @@ partial class BuildTask
 
     AbsolutePath ReleaseManifestFile => PackagesDirectory / "release-manifest.json";
     AbsolutePath BuildOutputsMarkerFile => ArtifactsDirectory / ".build-outputs" / "build-outputs.json";
-    AbsolutePath ToolManifestFile => RootDirectory / ".config" / "dotnet-tools.json";
+    AbsolutePath ToolManifestFile => RootDirectory / "dotnet-tools.json";
     AbsolutePath DirectoryBuildPropsFile => RootDirectory / "Directory.Build.props";
 }

docs/docfx.json

@@ -0,0 +1,34 @@
+{
+  "metadata": [],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "index.md",
+          "quick-start-release.md",
+          "github-workflows-guide.md",
+          "toc.yml"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default"
+    ],
+    "globalMetadata": {
+      "_appTitle": "dotnet.CI.template Docs",
+      "_appFooter": "dotnet.CI.template",
+      "_enableSearch": true
+    },
+    "sitemap": {
+      "baseUrl": "https://agibuild.github.io/dotnet.CI.template/"
+    }
+  }
+}

docs/github-workflows-guide.md

@@ -87,7 +87,7 @@ push / PR to main + weekly
 - 可选：配置 wait timer、deployment branches（限制为 `main`）
 
 ### `github-pages` environment（可选）
-如果使用 DocFX 文档部署：
+仓库已内置 `docs/docfx.json`，如需启用文档发布：
 - Settings → Pages → Source 选择 GitHub Actions
 - environment `github-pages` 会自动创建
 - 预期文档地址：`https://<owner>.github.io/<repo>/`（本仓库为 `https://agibuild.github.io/dotnet.CI.template/`）

docs/index.md

@@ -0,0 +1,14 @@
+# dotnet.CI.template 文档首页
+
+这是一个开箱即用的 .NET CI/CD 模板，目标是把构建、测试、发布和文档部署标准化。
+
+## 你可以从这里开始
+
+- [Quick Start: Release in 2 Minutes](quick-start-release.md)
+- [GitHub Workflows 使用指南](github-workflows-guide.md)
+
+## 文档发布说明
+
+- 预期文档地址：`https://agibuild.github.io/dotnet.CI.template/`
+- 工作流会在 `deploy-docs` job 中执行 `dotnet docfx docs/docfx.json`
+- 若缺少 `docs/docfx.json` 或未启用 Pages，文档部署会被跳过

docs/toc.yml

@@ -0,0 +1,6 @@
+- name: 首页
+  href: index.md
+- name: 快速发版
+  href: quick-start-release.md
+- name: Workflows 指南
+  href: github-workflows-guide.md

dotnet-tools.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.78.5",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
+    }
+  }
+}