Home Assistant 文档站架构指南：一套 Jekyll 流水线如何生成 3000+ 页文档
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
Home Assistant 是全球使用最广泛的开源智能家居系统，而这个仓库正是它的官方文档站源码（home-assistant.io）。它解决了一个典型难题：上千个硬件集成、几百种触发器和模板函数，文档量庞大且必须跟着软件版本实时更新。整站由 Jekyll 静态站点生成器驱动：你只需要读懂 source/ 里的 Markdown 和 Rakefile 定义的构建流水线，就能明白每个页面从哪来、怎么变成 HTML，甚至本地一键起预览。
文档内容都放在哪：source 目录的内容组织
这一节回答：一个你浏览的文档页，对应仓库里的哪个文件？
所有页面源文件都在 source/ 下，按"内容类型"拆成多个 Jekyll collection（集合），在 _config.yml 里注册：
collections: integrations: output: true template_functions: output: true actions: output: true triggers: output: true conditions: output: true dashboards: output: true每个集合直接对应一个目录和一组 URL 前缀：
- source/_integrations/：约 1500 个 Markdown 文件，每个文件是一个品牌/协议集成（MQTT、Hue、Zigbee 等）的接入指南，最终发布到
/integrations/<品牌>/。 - source/_actions/、source/_triggers/、source/_conditions/：自动化三大件，按
领域.动作名.markdown命名，如light.turn_on.markdown。 - source/getting-started/：新手入门系列，包括实体概念、自动化入门等页面。
- source/_dashboards/：仪表盘卡片与视图的官方说明。
内容组织上有个值得注意的细节：_integrations/下的文件名和发布 URL 一一对应（mqtt.markdown → /integrations/mqtt/），这让"想给某品牌补文档"这件事定位成本极低——找文件、改文件、提交即可。
一次构建都干了什么：Rakefile 流水线拆解
这一节回答：从 Markdown 到可发布的 static 站点，中间经历了哪些步骤？
构建入口是 Rakefile，核心任务按固定顺序执行，最后一步才是jekyll build：
sass_compile = "sass #{sass_dir}/:#{source_dir}/stylesheets/ " \ "--style=compressed --no-source-map" # generate 任务顺序: # 1. 拉取实时数据 (analytics_data / alerts_data / version_data ...) # 2. 编译 SCSS 样式 # 3. jekyll build → public/ 静态站点样式方面，sass/ 目录下是基于 inuitcss 骨架的 SCSS 源码，--style=compressed压缩后直接输出到 source/stylesheets/，供 Jekyll 当作普通静态文件拷贝。
Jekyll 阶段，plugins/ 目录里的 30 个自定义 Ruby 文件在渲染 Markdown 时介入（下一节细讲），把普通静态站点生成变成了带"内容校验 + 数据索引"的文档工厂。
构建完的public/就是完整站点。本地预览只需一条命令：bundle exec rake preview，Rakefile 会同时启动 Jekyll 增量构建、Sass 监听和 rackup 服务，浏览器打开http://localhost:4000即可看到改动的即时效果。
文档页靠什么"聪明"：30 个自定义 Jekyll 标签
这一节回答：普通 Markdown 表达不了的文档元素，是怎么做出来的？
plugins/ 里每个.rb文件注册一个 Liquid 标签或生成器。两个最有代表性的：
configuration（plugins/configuration.rb）：把一段 YAML 元数据渲染成带类型标注、"必填/可选"徽标、默认值和类型超链接的标准参数表，并当场校验类型是否合法、布尔项是否写了默认值——文档写错，构建直接报错。- 术语提示（plugins/terminology_tooltip.rb）：从 source/_data/glossary.yml 词汇表查术语，自动给"实体""触发器"这类词挂上悬停释义，全站术语口径统一。
更妙的是联动生成：plugins/doc_collections_data.rb 会扫描全部 actions/triggers/conditions 文档里的{% options_yaml %}字段定义，聚合成 JSON；plugins/doc_data_file.rb 再把它打包成一个带内容哈希命名的 JS 文件（如doc-data-3f8a2b1c9d0e.js）。前端加载这份索引后，你在任何文档里看到light.turn_on，鼠标悬停就能看到参数提示和跳转链接。因为文件名带哈希，浏览器可以放心永久缓存，部署新版本时自动失效换新。
整个构建过程可以浓缩成一张时序图：
静态站点如何显示实时数据：构建时拉取策略
这一节回答：纯静态 HTML 页面里，"当前稳定版 2026.x"、安全告警这类动态内容从哪来？
答案是在构建时拉取，而非请求时。Rakefile 里一组*_data任务各负责一条数据管道，结果落地到 source/_data/：
| Rake 任务 | 拉取来源 | 落地文件 |
|---|---|---|
version_data | version.home-assistant.io/stable.json | 版本数据（当前稳定/ beta 号） |
alerts_data | alerts.home-assistant.io/alerts.json | 安全告警列表 |
analytics_data | analytics.home-assistant.io/data.json | 用户与集成统计 |
wwha_data | works-with.home-assistant.io/devices.json | "Works with Home Assistant" 兼容设备 |
meetups_data | Open Home Foundation 事件 API | 社区线下聚会日程 |
页面里再用 Liquid 语法{{ site.data.xxx }}直接引用。所有任务都做了降级处理——比如聚会数据拉取失败时，会保留上一次的文件（没有就写空数组），保证外部 API 抖动永远不会卡死整个构建。这正是静态站能承载"实时感"页面的通用做法：把动态性压缩到发布环节。
速查表与上手建议
这一节给你一张仓库地图，外加两条可以立刻动手的路径。
| 路径 | 作用 |
|---|---|
| source/ | 全部页面 Markdown 内容 |
| source/_integrations/ | 约 1500 个集成接入指南，文件名即 URL |
| source/_actions/ / source/_triggers/ / source/_conditions/ | 自动化三大件的逐条文档 |
| source/_data/ | 构建时拉取的实时数据 + 词汇表等静态数据 |
| plugins/ | 自定义标签与生成器：配置表、术语提示、索引 JS |
| sass/ | inuitcss 骨架 + 站点样式 SCSS 源码 |
| Rakefile | 构建流水线：数据拉取、样式编译、preview本地预览 |
| _config.yml | Jekyll 主配置：collections、URL 规则、站点元信息 |
| astro/ | 新版 Astro 技术栈，目前仅输出到不被链接的/astro-preview/路径，属迁移过渡期 |
两条上手建议：
- 本地跑一遍再读代码：
git clone https://gitcode.com/GitHub_Trending/ho/home-assistant.io，然后bundle install && bundle exec rake preview，改任意一篇 Markdown 看 4000 端口的增量重建，比干读构建脚本快得多。 - 从"补一行文档"开始参与：挑一个你用过的品牌，打开 source/_integrations/ 下对应文件；参数表不用手写 HTML，把元数据写进
{% configuration %}块，剩下的由标签自动生成、由构建校验。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
