README.md

OpenRemote Documentation

This repository contains the OpenRemote documentation published at docs.openremote.io.

The documentation is written in Markdown and built using Docusaurus. The OpenAPI documentation is generated using the Docusaurus OpenAPI Docs plug-in.

Documentation versions

The documentation website contains two kinds of documentation:

• Next contains documentation for the next OpenRemote release. Its source files are stored in docs.
• Released versions are snapshots created for published OpenRemote releases. Their source files are stored in versioned_docs.

The latest released version is shown by default on the documentation website. Use the version dropdown in the navigation bar to view Next or an older release.

The released versions that are currently included in the website are listed in versions.json.

A documentation version is normally created after every major or minor OpenRemote release.

A separate documentation version is not normally created for patch releases. Patch releases have a limited scope and generally do not introduce enough documentation changes to justify another complete documentation snapshot. Corrections that also apply to the current release can instead be added directly to its existing documentation version.

For more information, see the Docusaurus versioning documentation.

Writing documentation

Documentation pages are written using Markdown with additional features provided by Docusaurus and MDX.

See the Docusaurus Markdown features documentation for a complete overview.

Front matter

A document can begin with optional YAML front matter enclosed by --- lines:

---
title: Working with agents
description: Configure agents and protocol integrations in OpenRemote.
sidebar_label: Agents and protocols
---

# Working with agents

Useful front-matter properties include:

• title: the document title used by Docusaurus and page metadata;
• description: the page description used by search engines and link previews;
• sidebar_label: an alternative, shorter title for the sidebar;
• sidebar_position: an explicit position in an autogenerated sidebar;
• slug: a custom URL for the page;
• keywords: search-engine metadata for the page.

Most OpenRemote documentation is placed in autogenerated sidebars. Numeric prefixes in file and directory names are used to keep pages in a predictable order. Use sidebar_position only when the normal file ordering is not sufficient.

Avoid defining a custom id or slug unless there is a specific reason to change the generated document identifier or URL. Changing an existing identifier or URL can break incoming links.

See the Docusaurus docs front-matter reference for all supported properties.

Admonitions

Use Docusaurus admonitions to highlight information that deserves special attention.

Available types include note, tip, info, warning, and danger:

:::note

This information is useful but does not require immediate action.

:::

:::tip

This is a recommended way to complete the task.

:::

:::warning

Changing this setting may affect an existing deployment.

:::

:::danger

This action permanently removes the stored data.

:::

An optional title can be added after the admonition type:

:::warning Back up your data

Create a database backup before continuing.

:::

Use admonitions sparingly. Important information should still be included in the normal flow of the documentation rather than placing most of a page inside highlighted blocks.

See the Docusaurus admonitions documentation for more examples.

Internal links

Use relative Markdown file links including the .md or .mdx extension when linking to another documentation page.

For example, from a file in the same directory:

[Preparing the environment](./010-preparing-the-environment.md)

To link to a document in another directory:

[Quick start](../../quick-start.md)

To link to a specific heading:

[Setting the working directory](./020-setting-up-an-ide.md#setting-the-working-directory)

Do not use a public https://docs.openremote.io URL for links between pages in this repository.

For example, do not use:

[Manager UI](https://docs.openremote.io/docs/user-guide/manager-ui/)

Also avoid site-root links such as:

[Manager UI](/docs/user-guide/manager-ui/)

Instead, link to the source Markdown file using a relative path:

[Manager UI](../020-manager-ui/10-manager-ui.md)

Docusaurus resolves relative file links during the build. This means that:

• links work when viewing Markdown files on GitHub;
• links work when serving the documentation locally;
• links work when the website is deployed below a different base URL;
• Docusaurus can validate whether the target exists;
• custom document slugs can change without requiring every link to be updated;
• a page in a released documentation version links to the corresponding page in that same version.

The final point is particularly important for OpenRemote documentation. A link on a page in version 1.28.0 should normally open the corresponding page in version 1.28.0, not the latest or Next version.

A hard-coded https://docs.openremote.io link bypasses Docusaurus version-aware routing. It may send users away from the documentation version they are currently reading and makes local deployments harder to test.

Use full URLs only for external websites:

[Docusaurus](https://docusaurus.io/)

See the Docusaurus Markdown links documentation for more information.

Images

Reference documentation images using relative paths:

![OpenRemote architecture](./img/architecture.jpg)

Keep images close to the documentation that uses them where practical. Ensure the relative path works from the source document rather than relying on the final website URL.

Optimize images before committing them. The contents of docs are copied when a new documentation version is created, so unnecessarily large images may be duplicated across multiple versions and permanently increase the repository and checkout size.

Use an appropriate optimizer for the image format, for example:

• zopflipng for lossless PNG compression;
• jpegoptim, jpegtran, or MozJPEG for JPEG images;
• svgo for SVG images.

For a PNG image, a command could look like:

zopflipng image.png image-optimized.png

Verify the optimized image before replacing the original. Screenshots must remain readable, particularly where they contain small text or interface controls.

Also consider cropping images to the relevant content and reducing excessive image dimensions.

Installation

Install the dependencies:

yarn

The required Yarn version is configured through the packageManager property in package.json.

Local development

Start the local development server:

yarn start

This opens the documentation website in a browser. Most changes are reflected without restarting the server.

For faster development, the local development server only includes the Next documentation from docs.

Build

Create a production build containing all versions listed in versions.json and Next:

yarn build

The generated static website is written to the build directory.

Serve the production build locally using:

yarn serve

Use a production build when testing released documentation, version switching, generated REST API documentation, or changes to the complete website.

Testing pull requests

The continuous-integration workflow builds documentation pull requests to check that the website can be generated successfully.

Pull requests currently do not receive a publicly accessible documentation preview. Support for deployable pull-request previews is tracked in issue #61: Add PR preview support.

Routine documentation changes normally do not need to be tested locally when the CI build succeeds. This includes correcting or adding text, adding or removing ordinary documentation pages or images, and updating simple internal links.

Changes with a major impact should be tested and verified locally before they are merged. Examples include substantial navigation changes, Docusaurus configuration or styling changes, large documentation reorganizations, versioning changes, and large generated REST API documentation updates.

For major changes affecting the complete or versioned website, run:

yarn build
yarn serve

Screenshots can be added to the pull-request description when they help reviewers assess visual changes that cannot yet be viewed through an online preview.

OpenAPI documentation

The REST API documentation is generated from the OpenAPI specifications in the api directory.

Updating and generating the REST API documentation is currently a manual process.

To update it:

1. Update the api/openapi.yaml specification.

   It can be downloaded from a running OpenRemote instance, for example:

   wget -O api/openapi.yaml http://localhost:8080/api/master/openapi.yaml

2. Replace the server URL in api/openapi.yaml from /api/{realm} to https://demo.openremote.io/api/{realm}:

   sed -i 's#/api/{realm}/#https://demo.openremote.io/api/{realm}/#g' api/openapi.yaml

3. Remove the previously generated OpenAPI documentation:

   yarn clean-api-docs all

4. Regenerate the OpenAPI documentation:

   yarn gen-api-docs all

5. Verify the generated changes and create a production build:

   yarn build

Generated OpenAPI documentation under docs follows the same versioning rules as the other documentation. Changes under docs appear under Next until a new documentation version is created.

Automating this process is planned and tracked in issue #26: Automate REST API documentation generation.

Creating a documentation version

Creating a released documentation version is currently a manual process.

Before creating a version:

1. Confirm that the corresponding major or minor OpenRemote release has been published or is ready to be published.
2. Make sure the contents of docs represent that OpenRemote release.
3. Update and regenerate the REST API documentation.
4. Make sure images and other large assets have been optimized.
5. Make sure yarn build completes successfully.
6. Make sure all intended changes have been merged.

Create the new documentation version using:

yarn docusaurus docs:version <version>

For example:

yarn docusaurus docs:version 1.29.0

This creates:

• versioned_docs/version-<version>, containing a snapshot of docs;
• versioned_sidebars/version-<version>-sidebars.json, containing a snapshot of the sidebar;
• a new entry in versions.json.

Removing an older version from the website

Each version included in versions.json increases the production build time and memory usage.

When adding a new released version, review whether the oldest version should be removed from the active documentation website. To do so, remove its entry from versions.json.

Do not delete its files from:

versioned_docs/version-<version>
versioned_sidebars/version-<version>-sidebars.json

The historical Markdown snapshot remains in the repository even though it is no longer part of the deployed documentation website.

We are investigating ways to make older archived versions available separately without requiring every historical version to be built as part of the main documentation website. This work is tracked in issue #141: Archive old documentation versions as artifacts.

Completing the release

After creating the new version and updating versions.json where appropriate, run:

yarn build

Review the generated files and commit all changes.

The new version becomes the latest released documentation after the changes are merged into main and the deployment workflow completes.

Improvements to the release process are tracked in:

• issue #26: Automate REST API documentation generation;
• issue #141: Archive old documentation versions as artifacts;
• issue #166: Add documentation to Release Management docs;
• issue #184: Document deployment of new commits without a version change.

The longer-term goal is to automate more of the REST API generation, documentation version creation, current-version update, and archival process. Until that automation is implemented, maintainers must perform and review these steps manually.

Deployment

GitHub Actions builds the documentation for pull requests targeting main.

Pull-request builds validate that the documentation can be generated successfully, but they are not deployed and do not currently provide a preview URL.

When changes are pushed or merged into main, GitHub Actions automatically builds and deploys the website to GitHub Pages.

The workflow can also be started manually from the Actions tab using the workflow_dispatch trigger.

Frequently asked questions

Why do I not see my merged changes on the documentation page?

Changes made to files under docs belong to the unreleased Next documentation.

The documentation website displays the latest released version by default. Select Next from the version dropdown to see the changes.

After the next major or minor OpenRemote release, a new documentation version is created from the contents of docs. That version then becomes the default documentation.

Also check that the pull request has been merged into main, the GitHub Actions deployment completed successfully, and you are viewing the expected documentation version.

Why was no documentation version created for a patch release?

Documentation versions are normally created for major and minor OpenRemote releases, but not for patch releases.

Patch releases have a limited scope and normally contain targeted bug fixes rather than significant new functionality. Creating and maintaining a complete documentation snapshot for every patch release would add build and maintenance overhead for relatively few documentation differences.

Corrections relevant to the current release can be applied directly to its existing documentation version without creating a new version.

How do I make a documentation change available in the current release immediately?

Update both:

docs/<path-to-document>

and the corresponding file in the latest released version:

versioned_docs/version-<latest-version>/<path-to-document>

Updating the released copy makes the change visible in the current documentation after it is merged into main and deployed.

The copy under docs should normally be updated as well. Otherwise, the correction may disappear when the next documentation version is created.

For structural changes, you may also need to update the corresponding file under versioned_sidebars.

Always run yarn build when changing released documentation.

Should every change be added to the current released version?

No.

Add a change only to docs when it describes functionality intended for the next OpenRemote major or minor release but not available in the current release.

Update both docs and the latest released version when correcting or clarifying documentation that also applies to the current release.

Older released versions should normally remain unchanged unless the correction is also relevant to those versions.

Should a patch-release change be added to Next or the current version?

When a patch release changes behaviour that users need to understand, update both the current released documentation version and docs.

Do not create a separate Docusaurus documentation version solely for the patch release.

Why can I see my changes with yarn start, but not in the released documentation?

The local development server only loads the Next documentation from docs.

To test released documentation and the version dropdown, create and serve a production build:

yarn build
yarn serve

Can I preview a pull request online?

Not currently.

The pull-request workflow checks that the documentation builds, but it does not deploy the result or provide a preview URL. Adding this functionality is tracked in issue #61: Add PR preview support.

Only changes with a major visual, structural, navigational, generated-content, or versioning impact generally need to be tested locally. Routine documentation changes can normally rely on the CI build.

Why is my pull request not visible on the public documentation website?

Pull requests are built for validation but are not deployed.

The public website is updated only after changes have been merged into main and the deployment workflow has completed successfully.

Why does an internal link open the wrong documentation version?

The link probably uses a public website URL or site-root path instead of a relative Markdown file path.

Avoid links such as:

[Manager UI](https://docs.openremote.io/docs/user-guide/manager-ui/)

Instead, link to the source Markdown file using a relative path:

[Manager UI](../user-guide/020-manager-ui/10-manager-ui.md)

Docusaurus can then rewrite the link so it points to the target page in the currently viewed documentation version.

Why should images be optimized before committing them?

Images stored alongside versioned documentation are copied when a new documentation version is created.

An unnecessarily large image may therefore be stored repeatedly in docs and several versioned_docs directories. Optimizing the original before it is versioned avoids multiplying that overhead.

Use a lossless optimizer such as zopflipng for PNG screenshots where possible, and verify that text and interface details remain readable.

Why are older versions removed from the version dropdown?

Every version listed in versions.json must be included in the Docusaurus production build. Keeping every historical version active indefinitely increases build time and memory usage.

When a new major or minor documentation version is created, an older version may therefore be removed from versions.json.

Its Markdown and versioned sidebar files remain in the repository. We are investigating a separate archival mechanism so these older snapshots can be made available without rebuilding all of them as part of the main website. See issue #141: Archive old documentation versions as artifacts.

When should a new documentation version be created?

Create a new documentation version after each major or minor OpenRemote release.

Do not create a documentation version for every merged documentation pull request, ordinary corrections to existing documentation, or patch releases with limited documentation changes.

Until the next major or minor release is published, ongoing changes remain available under Next.