Home Assistant website is an open-source Jekyll-based documentation template that generates the official user documentation and website for the Home Assistant home automation platform at home-assistant.io.
What is the Home Assistant website?
The Home Assistant website is a Jekyll static site that compiles Markdown documentation, blog posts, and changelogs into the public site at home-assistant.io. It is maintained by the Home Assistant community under the Open Home Foundation and licensed under CC BY-NC-SA 4.0. The source repository contains the full content for the website, organized into documentation pages, blog posts, and release notes.
What makes the Home Assistant website stand out?
- Multi-branch deployment — The repository uses three branches:
currentfor production (www.home-assistant.io),rcfor beta (rc.home-assistant.io), andnextfor development (next.home-assistant.io), so content can be staged before release. - Jekyll and Markdown — All user documentation is written in Markdown and built with the Jekyll static site generator, making it straightforward for contributors to edit pages without a database or backend.
- Netlify preview deployments — Every pull request gets an automatic Netlify preview URL linked in the first PR comment, so reviewers can see rendered changes before merging.
- Local preview with rake — Running
bundle exec rake previewserves the site athttp://127.0.0.1:4000; passing an IP likebundle exec rake preview[192.168.0.123]makes it available on a network. - Blog isolation workflow — Because changelogs slow down site generation,
bundle exec rake isolate[filename-of-blogpost]temporarily removes all but one blog post, andbundle exec rake integraterestores them. - Open licensing — The content is shared under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 license, allowing derivative documentation with attribution.
Who should use the Home Assistant website template?
- Home Assistant users can read complete user documentation on home-assistant.io for setup, configuration, and automation guidance.
- Documentation contributors can fork the repository, edit Markdown files, open pull requests, and get an automatic Netlify preview before their changes go live.
- Home Assistant developers can publish changelogs and feature announcements by adding blog posts and release notes to the same Jekyll structure.
What can you do with the Home Assistant website?
- Read official documentation — Access setup guides, configuration references, and integration details for Home Assistant, all generated from the Markdown source.
- Contribute a documentation fix — Submit a pull request to the current branch and receive a Netlify preview to verify the rendered page.
- Preview locally while writing — Use
bundle exec rake previewto run the full Jekyll build on your own machine, with the option to bind it to a local IP for testing on other devices. - Isolate blog posts during large edits — Use the
rake isolatecommand to speed up site generation when working on a single changelog post.
How does the Home Assistant website work?
The site is built by installing the Ruby dependencies with Bundler and running bundle exec rake preview, which starts a local Jekyll server. When a pull request is opened, Netlify automatically builds the branch and creates a preview deployment linked in the PR comment. Changes merged into the current branch are deployed to production at home-assistant.io, while the rc and next branches serve beta and development versions.
FAQ
Is the Home Assistant website free to use?
Yes, the site content and source are freely accessible. The documentation is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0, which permits sharing and adaptation with attribution for non-commercial purposes.
How do I preview the website locally?
Install the project dependencies with Bundler and run bundle exec rake preview. The site will be served at http://127.0.0.1:4000 by default, or you can pass an IP address as a parameter to serve it on your local network.
Which branches deploy to which sites?
The current branch builds production at www.home-assistant.io, the rc branch builds beta at rc.home-assistant.io, and the next branch builds development at next.home-assistant.io. Netlify also creates preview deployments for every pull request.
What license applies to the content?
The content is licensed under CC BY-NC-SA 4.0, the Creative Commons Attribution-NonCommercial-ShareAlike license. This means you can share and adapt the documentation for non-commercial use if you give credit and share under the same license.
