百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
O

openhab-docs

> 编程语言
开源

此仓库包含 openHAB 的文档。

290 stars0 点赞3 次浏览
访问官网GitHub

工具介绍

此仓库包含 openHAB 的文档。

openHAB Documentation Project

Introduction

This repository contains the documentation for openHAB.x.

The result is available at https://openhab.org/docs/ and https://openhab.org/addons/.

How it works

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.

So I cannot improve an add-on article here?

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.

Contributing to the Documentation

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.

A few words on animated GIFs

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:

  • Keep them short: Try to limit the duration of the GIF to a few seconds. If you need to show a longer process, consider breaking it into multiple shorter GIFs.
  • Optimize the file size: Use tools like Licecap to capture animated GIFs on Windows, or Gifsicle to optimize existing GIFs. Usually, you can reduce file size significantly by reducing the number of colors to a palette of 256 colours: gifsicle -O3 --colors 256 -i input.gif -o output.gif
  • Use them sparingly: Only use animated GIFs when they add significant value to the documentation. If a static image can convey the same information, prefer the image.

Inline images

Regular 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:

xml

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.11

Next, you can build & serve the documentation preview:

bash
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 preview

The 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:

So what are the other branches for?

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.

Automatically Generated Parts

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.

How the documentation build works

Snapshot Documentation: next.openhab.org

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:

  1. Runs automatically on pushes to the main branch, or on a nightly cron schedule.
  2. Clones both the main and final branches.
  3. Runs the Ruby pipeline (ruby scripts/fetch-external-content.rb and ruby scripts/prepare-docs.rb --no-clean --no-placeholders).
  4. Commits the updated documentation and assets to the final branch.

Commits pushed to the final branch automatically trigger our website hosting service to redeploy the preview/next documentation.

Stable Documentation: www.openhab.org

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.

Documentation Versioning

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:

  • Versions like "2.1.0" are marked by git tags.
  • Based on tags branches like "2.1-patch" are created, to include later discovered changes (like fixed links).

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:

Issues· 81 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言