企业官网建设流程全解析

ArcKit /arckit:pages教程：把架构文档发布为可交互的GOV.UK风格文档站

【免费下载链接】arc-kitThe Enterprise Architecture Governance Harness — strategy, architecture, delivery, and assurance using AI coding assistants项目地址: https://gitcode.com/GitHub_Trending/ar/arc-kit

ArcKit 是一个企业架构治理工具包（Enterprise Architecture Governance Harness），它的/arckit:pages命令可以把仓库中所有架构文档一键发布为免费、可交互的 GOV.UK 风格文档站：自带治理仪表盘、Mermaid 图表渲染和文档依赖图谱，无需任何后端，部署到 GitHub Pages 或任意静态托管即可上线。

为什么需要架构文档站？

用 ArcKit 做架构治理时，仓库里会积累大量标准文档：需求（REQ）、风险登记册（RISK）、架构决策记录（ADR）、Wardley 地图（WARD）……它们分散在projects/各目录中，靠文件管理器或 IDE 逐一翻找效率很低。

/arckit:pages的价值就在于：

• 零后端：生成的是纯静态站点，文档由浏览器按需加载
• 零依赖：仪表盘与图谱使用原生 SVG，无构建步骤
• 政府级视觉：采用英国 GOV.UK Frontend 设计系统，专业、可访问、移动端自适应
• 随处可部署：GitHub Pages、Netlify、Vercel、S3 均可

完整玩法见官方指南：docs/guides/pages.md

一键生成步骤：/arckit:pages 如何工作

在支持 ArcKit 插件的 AI 编程助手中，只需执行一条命令：

/arckit:pages Generate documentation site for this repository

命令背后的 sync-guides hook 会在后台自动完成全部工作，你不需要写任何代码：

执行完毕后，助手会直接输出一份统计摘要：发现多少个项目、索引了多少份文档、图 / 决策记录 / 供应商文档各有多少，方便你立刻核对。

命令的完整定义可参考 plugins/arckit-claude/commands/pages.md，独立版（不装完整插件也可用）在 plugins/arckit-claude/commands-standalone/pages.md。

生成的文档站长什么样？

治理仪表盘：文档站的默认首页

打开站点默认进入仪表盘（Dashboard），所有数据完全由manifest.json客户端计算：

• KPI 卡片：项目总数、文档总数、架构决策数、平均工件覆盖率
• 文档分类环形图：按 Discovery、Planning、Architecture、Governance 等分类分布
• 项目覆盖率条形图：每个项目按绿（≥80%）/ 黄（≥50%）/ 红（<50%）着色，缺口一目了然
• 治理覆盖清单：检查关键工件类型在组合层面是否存在
• 会话遥测面板：若仓库有docs/telemetry.json，还会展示最近 10 次 AI 会话的工具调用与延迟统计

Mermaid 图表自动渲染

文档中所有 Mermaid 代码块都会被自动渲染——流程图、时序图、C4 图、ER 图、甘特图等开箱即用，架构师再也不用"先写图、再截图、再贴进文档"。

Document Map：让文档依赖关系可视化 🗺️

这是站点最惊艳的功能：每份文档变成一个节点，文档间的交叉引用变成连线，按治理域分层着色。

几个细节非常实用：

• 孤儿检测：没有任何引用关系的文档会显示虚线边框——孤立的"风险登记册"意味着没人把风险关联回需求
• 新鲜度指示：节点右上角绿点 = 7 天内修改，黄点 = 7~30 天，无点 = 超过一个月，治理评审时扫一眼就知道哪些文档过期了
• 时间线视图：切换后文档沿时间轴排布，自动按周 / 月 / 季度选粒度，直观看到文档是怎么演进的
• 交互探索：悬停高亮连接、点击直接打开文档、按项目过滤

详细原理与效果见 Document Map 文章。

GitHub Pages 发布：5 步上线

生成完成后，把docs/提交推送，然后：

1. 进入仓库 Settings
2. 打开Pages设置区
3. Source 选择 "Deploy from a branch"
4. Branch 选main，文件夹选/docs
5. 保存

站点随即上线于https://{owner}.github.io/{repo}/。URL 采用哈希路由（#dashboard、#projects/001-name/ARC-001-REQ-v1.0.md），浏览器前进后退正常可用，单份文档也能分享直达链接，无需任何服务器配置。

进阶技巧：健康检查、SEO 与隐私控制

📊 接入健康评分：先运行/arckit:health JSON=true生成docs/health.json，再重跑/arckit:pages，仪表盘即显示项目健康度数据。指南：docs/guides/health.md

🔍 自带 SEO：生成的docs/index.html包含唯一<title>、meta description、Open Graph 卡片、Schema.org 结构化数据和 canonical 链接。绑了自定义域名？在docs/CNAME写入域名，Hook 会自动把 canonical 和 og:url 解析为你的正式 URL。

🔒 敏感内容不上搜索引擎：治理文档可能含敏感信息，可通过.arckit/templates-custom/pages-template.html模板覆盖注入<meta name="robots" content="noindex">，让站点公开可访问但不被索引。

♻️ 保留手写 llms.txt：docs/llms.txt每次生成都会重写，但如果你已手写了不带 ArcKit 生成标记的版本，会被自动保留——AI 助手发现文档的索引和人类维护的清单互不打架。

常见问题

不装完整插件能用吗？可以，独立版命令 单独放置，适合只想生成文档站的轻量场景。

支持中文文档吗？Markdown 全文渲染与 Mermaid 均支持，GOV.UK 样式对中英文排版均可用。

文档改了会自动更新吗？站点通过相对路径从仓库实时读取文档，推送新的 Markdown 后刷新页面即见最新内容，无需重新生成站点。

除了 GitHub Pages 还能发在哪？站点使用相对路径，Netlify / Vercel 需把发布目录设为仓库根目录，任意静态服务器直接托管整个仓库目录即可。

总结

/arckit:pages把"架构文档库"升级为"架构文档站"：一条命令生成 GOV.UK 风格的可交互站点，仪表盘量化治理缺口，Document Map 让文档依赖关系和过期文档无处遁形，五步即可上线 GitHub Pages。对于希望文档"可浏览、可度量、可分享"的架构团队，这是零成本获得专业文档站的最快路径。

【免费下载链接】arc-kitThe Enterprise Architecture Governance Harness — strategy, architecture, delivery, and assurance using AI coding assistants项目地址: https://gitcode.com/GitHub_Trending/ar/arc-kit