// the find
home-assistant/home-assistant.io
:blue_book: Home Assistant User documentation
The documentation source for Home Assistant, one of the largest open-source home automation projects. It's a Jekyll static site containing thousands of Markdown pages covering every integration, action, and concept in the platform. You'd land here if you're contributing docs, not if you're looking for the actual HA codebase.
The custom Jekyll plugin suite is genuinely well-built — plugins for tabbed blocks, terminology tooltips, configuration YAML rendering, and Jinja templating preview show real investment in documentation UX rather than plain Markdown dumps. The `bundle exec rake isolate[post]` workflow is a practical solution to the slow build problem caused by thousands of changelog posts. Netlify preview deployments per PR lower the barrier for doc contributors to verify their changes visually. The `.claude/skills/` directory indicates they've invested in AI-assisted doc authoring with structured skill definitions.
The repo is essentially unmergeable without understanding the full Jekyll plugin ecosystem — there's no architecture doc explaining what each plugin does or how they interact, so contributing anything non-trivial means reverse-engineering Ruby plugins. The source directory structure is enormous (thousands of `_actions/*.markdown` files), which makes local builds slow and navigation tedious without knowing exactly where you're going. The CC BY-NC-SA license means you can't use this documentation infrastructure or content commercially, which is a real restriction if you're building tooling around it. Dependency management is fragile — Ruby version pinned in `.ruby-version`, Node in `.nvmrc`, Bundler managing gems — three separate lockfiles to keep in sync.