This repository contains the documentation for openHAB.
This repository contains the documentation for openHAB.
This repository contains the documentation for openHAB.x.
The result is available at https://openhab.org/docs/ and https://openhab.org/addons/.
In this repo you can find and improve all general documentation contents.
In fact, that is all you can see in the main branch.
There are other read-only branches, which hold external content like the add-ons and concepts documentation, which is explained in more details below.
Correct, this is done in the original repository of the add-on. You may want to know how to find the right file in all of those repos? This is fairly easy: on most of the documentation pages on , you will find the following link at the bottom, which will point you directly to the file you want to improve.
When your improvement has been made and merged, we will get the updated article automatically through our build mechanism. This happens mostly once a day. Afterwards your change is included in the next build of the openHAB website.
The documentation is a community effort, so everyone is welcome to suggest changes, add new sections, and fix bugs. This is done exactly the same way as for the code repositories, simply through pull requests against this repo. When editing a page through the "Edit this page on GitHub" link on the website, you will be given the opportunity to create a pull request directly from GitHub. Please read our contribution guidelines and try to follow them as best as you can before submitting a change for review — but don't worry if you don't understand all of them, we will help you to get it right.
Animated GIFs are a great way to show how something works, but they can also be quite large in file size. To keep the documentation website fast and responsive, we have a few recommendations regarding animated GIFs:
gifsicle -O3 --colors 256 -i input.gif -o output.gifRegular markdown images work well for things like screenshots, but when documenting e.g. UIs, and you want to focus on a particular component on the screen, this might not be ideal. You have to explain for example "the button to the far right, second from the top", and this might not even be true on all devices and layouts. In situations like this, it can be better to make a small image of just the component, a button for example, and then use that inline in the text.
To achieve this, a small Vue component called InlineImage has been created.
Using it is outside "regular Markdown syntax", which is why it is explained here.
Here is an example of the syntax:
This component will transform into a regular HTML element, so any valid attributes can be used here too.
alt should be defined to have something to show if the image doesn't load for some reason.
:src must be specified using `require('./
…shell script nvm use rvm use
If `nvm` and/or `rvm` complain about the required versions not being installed, you can install them as following:
```shell script
nvm install 16.20.1
rvm install ruby-3.3.11Next, you can build & serve the documentation preview:
npm install # This needs to be run once for initialization
npm run fetch-external-content # Optional: Fetch external content (add-ons, ecosystem, etc.) locally
npm run serve-preview # Build and serve the local previewThe local preview is available under the following URLs:
This will also allow you to preview how the page renders on different devices using the respective browser tools:
We use them to bring together all relevant articles or to archive versioned content. Mostly, those branches will get updated automatically through our continuous integration builds. You can read a bit more below about our external resources and how we get them.
Those parts include all add-on documentation files, no matter if they are from the openhab-core repo, the openhab-addons repo, any special binding repos like org.openhab.binding.zwave or other repos like openhab-android.
We are keeping all those files at their original location, because it simply doesn't make sense to keep them here. Imagine you want to do an improvement of the Z-Wave binding and have to update the readme file in a completely different place. That's twice the effort, and also we would have to coordinate two Pull Requests. So we are saving time for everyone by keeping those files at their original location along with the code.
We use a GitHub Actions workflow and a Ruby-based pipeline to automatically gather external content and prepare the documentation for deployment:
External Content Gathering:
The script fetch-external-content.rb pulls and clones external repositories (like openhab-distro, openhab-addons, openhab-webui, openhabian, mobile apps, etc.), fetches add-on descriptions and features XML, processes the markdown documentation, and populates the addons and docs folders.
Documentation Preparation:
The script prepare-docs.rb processes the documentation directory, copies pages from src to docs, and handles placeholder pages.
These scripts are integrated into the Update Final Branch Docs GitHub Actions workflow. This workflow:
main branch, or on a nightly cron schedule.main and final branches.ruby scripts/fetch-external-content.rb and ruby scripts/prepare-docs.rb --no-clean --no-placeholders).final branch.Commits pushed to the final branch automatically trigger our website hosting service to redeploy the preview/next documentation.
Our stable documentation is built from the final-stable branch of this repository. It normally does not need to be updated, as there are no changes made to openHAB after a release that would require a change in the documentation. But as you might have already noticed, the final-stable branch does also include documentation for software from the openHAB ecosystem with its independent release cycles, e.g. openHABian or our mobile apps.
When a new release of such software is made, the final-stable documentation branch needs to be updated to reflect the changes.
This is done through the fetch_external_docs GitHub action workflows residing in the .github/workflows folder of the main branch.
The fetch_external_docs workflows are triggered by a new release of the software in question, and it will then create a PR to the final-stable branch with the latest documentation from the respective repository.
When one of these PRs is merged, the change to the final-stable branch will trigger a new build of the website, which will then be deployed to www.openhab.org.
Just as openHAB is released in versions, the documentation website provides fixed versions of the documentation articles, e.g., https://www.openhab.org/v2.2/installation/linux.html
Please see this issue for all details regarding the tagging and branching approach. In short, the following has to be considered:
When a version is tagged (or updated), a static version of the website has to be generated and copied into the correct sub-folder, this is currently a manual operation described succinctly here:
No open issues yet, or sync has not completed.