Spec Kit 文档系统详解：DocFX 本地构建、目录组织与 GitHub Pages 自动部署

Spec Kit 的官方文档并非静态托管的网页，而是一套基于 DocFX 构建的 Markdown 文档工程。本文以 docs/README.md 为核心，完整讲解文档源文件的组织结构、docfx 配置的关键字段，以及从本地 --serve 预览到 main 分支推送后自动发布到 GitHub Pages 的完整链路，帮助你在阅读文档之外，也能理解并复现 Spec Kit 文档从 Markdown 到站点的构建与部署全流程。

一、文档工程的定位与组成

docs/README.md 开宗明义：docs/ 目录保存的是 Spec Kit 文档的源文件（documentation source files），整个站点使用 DocFX 构建。从目录结构看，这套文档工程由以下几部分构成：

• 配置层：docs/docfx.json（DocFX 配置文件）、docs/toc.yml（目录树配置）；
• 内容层：首页 docs/index.md、安装指南 docs/installation.md、快速上手 docs/quickstart.md、升级指南 docs/upgrade.md、本地开发指南 docs/local-development.md，以及按主题划分的 community/、concepts/、guides/、install/、reference/ 等子目录；
• 样式层：docs/template/ 自定义 DocFX 模板（含 public/main.css）；
• 输出层：_site/ 为构建产物目录，由 git 忽略，不随源码提交。

docs/README.md 给出的文件结构清单与仓库实际内容完全一致：index.md 是文档主页，installation.md 与 quickstart.md 分别对应安装与上手两条主线，_site/ 是生成物。

二、本地构建：三步搭建文档预览环境

docs/README.md 给出了完整的本地构建步骤，共三步：

1. 全局安装 DocFX（以 .NET 全局工具形式分发）：

   dotnet tool install -g docfx
   

2. 进入 docs 目录并启动带服务模式的构建：

   cd docs
   docfx docfx.json --serve
   

   --serve 参数让 DocFX 在本地起一个静态服务，并在文件变更时支持快速迭代预览。

3. 浏览器访问 http://localhost:8080 查看渲染后的文档站点。

这三步与 CI 的构建逻辑保持同源：文档站点的构建入口始终是 docs/docfx.json，本地只是多了 --serve 便于实时预览。

三、docfx.json 逐字段解析：内容、资源与主题

理解 docs/docfx.json 是理解整个文档工程的关键。以下按构建管道顺序解读其核心字段。

3.1 content：哪些 Markdown 会被纳入构建

配置中定义了两个内容源（content sources）：

"content": [
  {
    "files": [
      "*.md",
      "toc.yml",
      "community/*.md",
      "concepts/*.md",
      "guides/*.md",
      "reference/*.md",
      "install/*.md"
    ]
  },
  {
    "files": [
      "../README.md",
      "../CONTRIBUTING.md",
      "../CODE_OF_CONDUCT.md",
      "../SECURITY.md",
      "../SUPPORT.md"
    ],
    "dest": "."
  }
]

• 第一个来源覆盖 docs/ 根目录下所有 *.md（含 index.md、installation.md、quickstart.md、history.md 等），以及五个一级子目录中的全部 Markdown；
• 第二个来源将仓库根目录的项目级文档（README.md、CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md、SUPPORT.md）通过 ../ 相对路径拉入文档站，并用 "dest": "." 平铺到站点根目录，使读者可以在同一站点内直接看到项目主 README 与贡献规范。

3.2 resource：静态资源映射

"resource": [
  { "files": [ "images/**" ] },
  { "files": [ "../media/**" ], "dest": "media" }
]

• docs/images/ 下的图片（如 spec-kit-logo.webp）直接随文档引用路径输出；
• 仓库根目录的 media/ 目录整体映射为站点的 media/，这样正文中引用 ../media/xxx.gif 的资源在站点上以 media/xxx.gif 的相对路径可访问。

3.3 template：默认模板 + 自定义模板叠加

"template": [ "default", "modern", "template" ]

DocFX 支持模板按序叠加：default 提供基础结构，modern 是官方现代主题，第三个 template 指 docs/template/ 目录下的自定义模板。该目录包含 public/main.css，从源码看其内容是用 GitHub Primer 调色板（--gh-blue: #0969da 等 CSS 变量）对主题做品牌化改造，并为深色模式定义了 [data-bs-theme="dark"] 下的对应变量，还针对首页定义了 body[data-layout="landing"] 的 Hero 区样式。

3.4 元数据与首页布局

"markdownEngineName": "markdig",
"dest": "_site",
"globalMetadata": {
  "_appTitle": "Spec Kit Documentation",
  "_appName": "Spec Kit",
  "_appLogoPath": "images/spec-kit-logo.webp",
  "_appFooter": "Spec Kit - A specification-driven development toolkit",
  "_enableSearch": true,
  "_gitContribute": { "repo": "...", "branch": "main" }
},
"fileMetadata": {
  "_layout": { "index.md": "landing" }
}

• "dest": "_site" 对应 docs/README.md 中提到的生成输出目录；
• _enableSearch: true 为站点启用站内搜索；
• fileMetadata 中的 _layout 把 index.md 指定为 landing 布局——这正是 docs/index.md 使用自定义 HTML 区块（Hero、pillars、导航卡片）而非普通文档布局的原因，也与 main.css 中 body[data-layout="landing"] 的选择器相呼应；
• 其余如 keepFileLink、disableGitFeatures 等字段保持默认值，说明站点启用了 git 集成功能（页面贡献链接、修订记录），与 _gitContribute 指向 main 分支的配置一致。

四、toc.yml：文档信息架构

docs/toc.yml 定义了侧边栏的完整目录树，从源码看其层级组织如下：

一级节点	包含条目
Home	index.md
Project History	history.md
Getting Started	Installation、Quick Start、Existing Projects、Upgrade，以及 install/ 下的 uv / PyPI / pipx / One-time (uvx) / Enterprise (Air-Gapped) 五个安装子指南
Reference	Overview、Core Commands、Integrations、Extensions、Presets、Workflows、Bundles、Agentic SDD、Agentic Bug Fix、Authentication 共 10 篇
Concepts	What is SDD?、Spec Persistence Models、Handling Complex Features、Spec of Specs
Development	Local Development、Evolving Specs、Monorepos
Community	Overview、Extensions、Presets、Bundles、Walkthroughs、Friends

这份目录树与 docfx.json 的 content 文件清单相互印证：install/、reference/、concepts/、guides/、community/ 五个子目录既是被构建的内容源，也是目录树的一级分支。修改文档结构时，两处需要保持同步。

五、部署链路：main 分支推送触发 GitHub Pages 发布

docs/README.md 指出：文档在推送 main 分支时自动构建并发布到 GitHub Pages，工作流定义在 .github/workflows/docs.yml。阅读该工作流源码，可以确认完整的触发与执行细节：

5.1 触发条件与权限

on:
  push:
    branches: ["main"]
    paths:
      - 'docs/**'
  workflow_dispatch:

• 只有默认分支且变更路径命中 docs/** 的推送才会触发构建，文档源文件与 CI 定义严格绑定在 docs/ 范围内；
• 同时支持 workflow_dispatch 手动触发，便于排障与补发；
• 权限最小化声明为 contents: read、pages: write、id-token: write，后者是 GitHub Pages 基于 OIDC 安全部署所必需的；
• concurrency: { group: "pages", cancel-in-progress: false } 保证同一时刻只有一个部署在跑，但不取消进行中的生产部署，避免发布被中途截断。

5.2 build 作业

build:
  if: github.repository == 'github/spec-kit'
  runs-on: ubuntu-latest

构建作业带有 github.repository 判定，从源码结构看这意味着 fork 仓库上的推送不会执行文档部署——部署只发生在源仓库本身。步骤依次为：

1. actions/checkout 并指定 fetch-depth: 0 拉取完整 git 历史（DocFX 的 git 功能需要完整历史来计算页面贡献与修订信息，与 docfx.json 中 disableGitFeatures: false 相配套）；
2. actions/setup-dotnet 安装 .NET 8.x 运行时；
3. dotnet tool install -g docfx 安装 DocFX——与本地构建第 1 步完全相同；
4. cd docs && docfx docfx.json 执行构建——与本地构建第 2 步相同，只是去掉了 --serve，产物输出到 docs/_site/；
5. actions/configure-pages + actions/upload-pages-artifact 将 docs/_site 作为部署工件上传。

5.3 deploy 作业

deploy:
  if: github.repository == 'github/spec-kit'
  environment:
    name: github-pages
    url: ${{ steps.deployment.outputs.page_url }}
  needs: build

部署作业依赖 build 成功，绑定 github-pages 环境（Pages 发布必须走该环境以获得权限校验），并调用 actions/deploy-pages 完成上线。整个链路可概括为：

docs/** 变更推送 main → checkout 完整历史 → .NET 8 + DocFX 构建 docs/_site → 上传工件 → deploy-pages 发布

对贡献者而言，这条链路意味着：只修改 docs/ 下的文件即可触发文档站更新，无需触碰任何 Python 源码或测试；而修改其他路径则不会触发文档流水线。

六、实践要点与文档工程内各文件的职责速查

结合 docs/README.md 与源码，整理出如下速查表，便于后续维护文档时快速定位：

目标	操作位置
新增一篇文档	在对应子目录新增 .md，并在 docs/toc.yml 对应节点登记 href
调整站点标题、Logo、页脚	docs/docfx.json 的 globalMetadata
更换/调整视觉主题	docs/template/public/main.css 等模板资源
在站点中展示仓库根目录文档	修改 docfx.json 第二个 content 来源的 files 列表
本地预览	dotnet tool install -g docfx 后 cd docs && docfx docfx.json --serve，访问 http://localhost:8080
触发线上更新	将 docs/** 变更推送至 main 分支（或在 Actions 中手动触发）

最后需要说明适用前提：本地构建要求机器已安装 .NET SDK（DocFX 以 dotnet tool 分发），--serve 的预览端口固定为 http://localhost:8080；CI 侧的构建与部署仅在源仓库上生效（github.repository == 'github/spec-kit' 判定），fork 用户可复用相同的 docfx.json 在本地构建，但不会拥有 Pages 自动部署能力。对于希望深入文档内容的读者，建议从 docs/quickstart.md 与 docs/installation.md 入手，再经由 docs/toc.yml 中列出的 Reference 与 Concepts 章节按需深入。