Home Assistant 文档站架构指南一套 Jekyll 流水线如何生成 3000 页文档【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.ioHome 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 buildsass_compile sass #{sass_dir}/:#{source_dir}/stylesheets/ \ --stylecompressed --no-source-map # generate 任务顺序: # 1. 拉取实时数据 (analytics_data / alerts_data / version_data ...) # 2. 编译 SCSS 样式 # 3. jekyll build → public/ 静态站点样式方面sass/ 目录下是基于 inuitcss 骨架的 SCSS 源码--stylecompressed压缩后直接输出到 source/stylesheets/供 Jekyll 当作普通静态文件拷贝。Jekyll 阶段plugins/ 目录里的 30 个自定义 Ruby 文件在渲染 Markdown 时介入下一节细讲把普通静态站点生成变成了带内容校验 数据索引的文档工厂。构建完的public/就是完整站点。本地预览只需一条命令bundle exec rake previewRakefile 会同时启动 Jekyll 增量构建、Sass 监听和 rackup 服务浏览器打开http://localhost:4000即可看到改动的即时效果。文档页靠什么聪明30 个自定义 Jekyll 标签这一节回答普通 Markdown 表达不了的文档元素是怎么做出来的plugins/ 里每个.rb文件注册一个 Liquid 标签或生成器。两个最有代表性的configurationplugins/configuration.rb把一段 YAML 元数据渲染成带类型标注、必填/可选徽标、默认值和类型超链接的标准参数表并当场校验类型是否合法、布尔项是否写了默认值——文档写错构建直接报错。术语提示plugins/terminology_tooltip.rb从 source/_data/glossary.yml 词汇表查术语自动给实体触发器这类词挂上悬停释义全站术语口径统一。更妙的是联动生成plugins/doc_collections_data.rb 会扫描全部 actions/triggers/conditions 文档里的{% options_yaml %}字段定义聚合成 JSONplugins/doc_data_file.rb 再把它打包成一个带内容哈希命名的 JS 文件如doc-data-3f8a2b1c9d0e.js。前端加载这份索引后你在任何文档里看到light.turn_on鼠标悬停就能看到参数提示和跳转链接。因为文件名带哈希浏览器可以放心永久缓存部署新版本时自动失效换新。整个构建过程可以浓缩成一张时序图静态站点如何显示实时数据构建时拉取策略这一节回答纯静态 HTML 页面里当前稳定版 2026.x、安全告警这类动态内容从哪来答案是在构建时拉取而非请求时。Rakefile 里一组*_data任务各负责一条数据管道结果落地到 source/_data/Rake 任务拉取来源落地文件version_dataversion.home-assistant.io/stable.json版本数据当前稳定/ beta 号alerts_dataalerts.home-assistant.io/alerts.json安全告警列表analytics_dataanalytics.home-assistant.io/data.json用户与集成统计wwha_dataworks-with.home-assistant.io/devices.jsonWorks with Home Assistant 兼容设备meetups_dataOpen Home Foundation 事件 API社区线下聚会日程页面里再用 Liquid 语法{{ site.data.xxx }}直接引用。所有任务都做了降级处理——比如聚会数据拉取失败时会保留上一次的文件没有就写空数组保证外部 API 抖动永远不会卡死整个构建。这正是静态站能承载实时感页面的通用做法把动态性压缩到发布环节。速查表与上手建议这一节给你一张仓库地图外加两条可以立刻动手的路径。路径作用source/全部页面 Markdown 内容source/_integrations/约 1500 个集成接入指南文件名即 URLsource/_actions/ / source/_triggers/ / source/_conditions/自动化三大件的逐条文档source/_data/构建时拉取的实时数据 词汇表等静态数据plugins/自定义标签与生成器配置表、术语提示、索引 JSsass/inuitcss 骨架 站点样式 SCSS 源码Rakefile构建流水线数据拉取、样式编译、preview本地预览_config.ymlJekyll 主配置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），仅供参考