# home-assistant/home-assistant.io: the source repository behind the Home Assistant documentation site

> This repository is not the Home Assistant application. It is the Jekyll and Astro source for the website that documents it, and the setup path runs through Ruby, Bundler and a Rake preview task.

**home-assistant/home-assistant.io** — :blue_book: Home Assistant User documentation

- Repository: https://github.com/home-assistant/home-assistant.io
- Website: https://www.home-assistant.io
- Stars: 9,871 · Forks: 8,586
- Language: HTML
- License: NOASSERTION
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/home-assistant-home-assistant-io

## The documentation site is the product here, not the smart home software

People searching for home assistant io download or home assistant io installation raspberry pi usually want the Home Assistant application, and this repository will not give it to them. The README opens by stating that this is the source for the Home-Assistant.io website, and the package name in package.json is home-assistant.io with the description "Home Assistant Website & Documentation". The code that runs a home is a different project; what lives here is the prose, the integration pages, the dashboards pages, the FAQ entries and the getting-started guides that describe it.

The audience is therefore narrow and specific. It is the person who wants to correct a typo in an integration page, add a new device write-up, or adjust a getting-started guide, and who is willing to run a Jekyll site locally to see the result. If you are evaluating Home Assistant as a platform to install in a house, this repository is the wrong entry point and the homepage link is the right one.

## Jekyll and Astro in one tree, with linting bolted on top

The repository layout shows two rendering stacks side by side. There is a top-level astro/ directory and a source/ directory, plus _config.yml, config.ru, a Rakefile, plugins/, sass/ and a Gemfile with a Gemfile.lock. Ruby and Bundler drive the Jekyll build; the Rakefile exposes the tasks the README documents. Astro is present in the same tree, which suggests the site is being moved or extended rather than rewritten in one step, and that a contributor may need to know which stack owns the page they are editing.

Quality control is enforced through Node tooling rather than through the Ruby side. The devDependencies in package.json include remark-cli with a set of remark-lint plugins (fenced code flags, heading increment, heading style, no shell dollars, ordered list marker style and value, prohibited strings, unordered list marker style) and textlint with rules for common misspellings and terminology. The scripts section wires these into named commands, and the textlint script scopes itself to specific source subdirectories: source/_docs, source/_faq, source/_integrations, source/_dashboards, source/cloud, source/getting-started, source/hassio and source/dashboards. That scoping is a useful signal about where the maintained prose actually lives.

## Installing the toolchain and previewing the site on port 4000

The README does not spell out dependency installation. It points to the developer documentation at developers.home-assistant.io/docs/documenting/ for setting up to contribute and for the pull request process, so treat that page as the authoritative setup guide. What the README does give is the preview command, which assumes a working Bundler environment and a checked-out set of gems.

The documented preview command starts the site on http://127.0.0.1:4000:

```bash
bundle exec rake preview
```

If the preview must be reachable from another machine, the README shows passing the target IP as a task argument, so the site is served on that address instead of the loopback interface:

```bash
bundle exec rake preview[192.168.0.123]
```

Generation is slow because release changelogs are posted to the site, and the README says this slows generation significantly. Two tasks exist to work around it. The isolate task takes the filename of the blog post you are working on and moves the other posts out of the way:

```bash
bundle exec rake isolate[filename-of-blogpost]
```

When you are finished, the integrate task moves the posts back:

```bash
bundle exec rake integrate
```

For prose checks, the package.json scripts run remark across the tree and textlint across the scoped source directories:

```bash
pnpm run markdown:lint
pnpm run textlint
```

Expect the preview to come up at the address you passed, and expect markdown:lint to be strict: it is invoked with --quiet --frail, so a single violation fails the run.

## The isolate and integrate tasks are a real workflow hazard

The isolate task physically moves blog posts out of the build to make generation faster. That is a sensible workaround for a documentation site that publishes long changelogs, but it creates a stateful working tree. If you run isolate and then forget integrate, your local build no longer reflects the repository, and any commit you make from that state can carry the removal. The README pairs the two commands but does not describe a guard, a check or a warning if you commit while isolated. The Rakefile is the place to look if you want to confirm what the task actually moves.

The second limitation is the stack split. With both a Jekyll-oriented source/ tree and an astro/ directory, plus Ruby, Bundler, Node, pnpm and a .mise.toml and .nvmrc pinning tool versions, the local environment has several ways to drift. Nothing in the README explains which pages are served by which generator, so a new contributor can spend time debugging a Ruby build for a page that is rendered elsewhere. The developer documentation is the only pointer offered.

A third boundary is licensing. The README carries a CC BY-NC-SA 4.0 badge and the repository LICENSE.md is reported as NOASSERTION by the hosting metadata. Those two signals do not obviously agree, and the non-commercial clause matters if you were thinking of reusing documentation text in a commercial product. The repository does not resolve the question for you.

## How this differs from building your own docs with a plain static site generator

A generic static site generator setup gives you a theme, a content folder and a deploy target. This repository gives you the same core plus a contribution contract. The contract is visible in the file list: CODEOWNERS assigns review responsibility, CLA.md defines what you sign, CODE_OF_CONDUCT.md sets behaviour expectations, AI_POLICY.md and the agent files (AGENTS.md, CLAUDE.md, GEMINI.md) constrain how automated contributions are produced, and .github/ holds the workflows.

The practical difference is where the friction sits. With a bare generator, friction is configuration. Here, friction is review: remark-lint-prohibited-strings and textlint-rule-terminology will reject wording that a plain Markdown build would happily publish, and the terminology rule in particular means the project enforces its own vocabulary. That is the opposite trade-off from a personal docs site, where you would rather publish than argue about a term. If you want a documentation site with no editorial gate, this repository is the wrong model to copy.

## Maintenance and the cost of keeping a fork in sync

The repository is not archived, and the last push was on 2026-09-21. That is a same-day signal, so the tree is moving, but it also means the cost of a long-lived fork is high: a documentation repository that changes daily will conflict with local edits quickly, and the isolate/integrate cycle makes it easy to carry unrelated changes into a branch. Contributing upstream through a pull request is the cheaper path than maintaining a copy.

Upgrades are split across two dependency systems. Ruby gems are pinned in Gemfile.lock and tool versions in .ruby-version and .mise.toml; Node packages are pinned in package-lock.json with pnpm pinned to 12.4.2 in devDependencies and a .nvmrc for the runtime. Bumping either side is a repository-level decision, not something a contributor should do casually inside a content pull request. On licensing, the README badge points to CC BY-NC-SA 4.0 while the host reports NOASSERTION for LICENSE.md; read LICENSE.md directly and, if you plan to reuse text commercially, get your own answer rather than relying on the badge.

## Conclusion

Adopt this repository if your job is writing or reviewing Home Assistant documentation, because the contribution path runs through the developer documentation and the preview task rather than through the product. Do not clone it expecting to install or run Home Assistant itself; the application lives elsewhere and this repository only builds the site that describes it. Before your first pull request, verify three things: that Ruby and Bundler are installed as the Gemfile expects, that the preview serves on the address you passed to the Rake task, and that the markdown and textlint scripts pass on the files you touched, since Netlify builds a preview deployment for every pull request and reviewers will look at it.

## FAQ

### What is home-assistant.io?

It is the source repository for the Home Assistant website at home-assistant.io, described in package.json as "Home Assistant Website & Documentation". It contains the documentation pages, not the Home Assistant application itself.

### Is home-assistant.io free?

The repository itself is public and the README carries a CC BY-NC-SA 4.0 licence badge, so the documentation source is available at no cost. The non-commercial clause in that licence is the part to read if you intend to reuse the text in a commercial product.

### Is there a better alternative to home-assistant.io for documentation?

The relevant comparison is not another smart home platform but another way of building the docs site. A plain static site generator gives you a theme and a content folder with far less process; this repository adds CODEOWNERS review, a CLA, an AI policy and remark and textlint rules that reject wording a bare Markdown build would publish.

### Is home-assistant.io safe?

The repository is public source for a documentation website, and the README points contributors at the developer documentation for the pull request process. Nothing in the README or package.json describes a security review of the site itself, so that question stays open.

## Sources

- [home-assistant/home-assistant.io on GitHub](https://github.com/home-assistant/home-assistant.io)
- [Issues](https://github.com/home-assistant/home-assistant.io/issues)
- [Project website](https://www.home-assistant.io)
- [README](https://github.com/home-assistant/home-assistant.io/blob/current/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/home-assistant-home-assistant-io