69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
---
|
||
title: "Documentation"
|
||
---
|
||
|
||
The user documentation is located at [https://www.home-assistant.io](https://www.home-assistant.io). This section is the place where we provide documentation and additional details about creating or modifying content.
|
||
|
||
The [home-assistant.io](https://home-assistant.io) website is built using [Jekyll](https://github.com/jekyll/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](https://daringfireball.net/projects/markdown/). To add a page, you don't need to know HTML.
|
||
|
||
## Small changes
|
||
|
||
You can use the "**Edit this page on GitHub**" link to edit pages, which will automatically create a fork and allow you to edit quickly. Keep in mind that you can't upload images while working this way. You work on your change and propose it via a Pull Request (PR).
|
||
|
||
Once you've created a Pull Request (PR), you can see a preview of the proposed changes by clicking *Details* against Netlify checker in the checkers section of the PR as soon as deployment is complete.
|
||
|
||
## Larger changes
|
||
|
||
For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process of working on the website is no different from working on Home Assistant itself.
|
||
|
||
### Developing with Visual Studio Code + devcontainer
|
||
|
||
The easiest way to get started with development is to use Visual Studio Code with devcontainers, in the same way as for working on Home Assistant Core development. Have a look at the [Development Environment](https://developers.home-assistant.io/docs/development_environment) page for instructions.
|
||
|
||
To review the changes, open the command palette and choose ´Tasks: Run Task´ and then ´Preview´.
|
||
|
||
### Manual environment
|
||
|
||
It is also possible to set up a more traditional development environment.
|
||
|
||
To test your changes locally, you need to install **Ruby** and its dependencies (gems):
|
||
|
||
- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already. Ruby version 3.1 is required.
|
||
- Install `bundler`, a dependency manager for Ruby: `gem install bundler` (You might have to run this command as `sudo`).
|
||
|
||
- Shortcut for Fedora:
|
||
|
||
```shell
|
||
sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle
|
||
```
|
||
|
||
- Shortcut for Debian/Ubuntu:
|
||
|
||
```shell
|
||
sudo apt-get install ruby ruby-dev ruby-bundler ruby-json g++ zlib1g-dev && bundle
|
||
```
|
||
|
||
- Shortcut for Mac (if the bundled Ruby doesn't work):
|
||
|
||
```shell
|
||
brew install ruby@3.1 && export PATH="/usr/local/opt/ruby@3.1/bin:$PATH"
|
||
```
|
||
|
||
|
||
- Fork the home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.io).
|
||
- In your home-assistant.io root directory, run `bundle` to install the gems you need.
|
||
|
||
Then you can work on the documentation:
|
||
|
||
- Run `bundle exec rake generate` to generate the very first preview. This will take a minute.
|
||
- Create/edit/update a page. The integration/platforms documentation is located in `source/_integrations/`. `source/_docs/` contains the Home Assistant documentation itself.
|
||
- Test your changes to home-assistant.io locally: run `bundle exec rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000). While this command is working, any changes to a file are automatically detected and will update the affected pages. You will have to manually reload them in the browser though.
|
||
- Create a Pull Request (PR) against the **next** branch of home-assistant.io if your documentation is a new feature, platform, or integration.
|
||
- Create a Pull Request (PR) against the **current** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation.
|
||
|
||
The site generated by `bundle exec rake` is only available locally. If you are developing on a headless machine, use port forwarding:
|
||
|
||
```shell
|
||
ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine
|
||
```
|