Skip to main content

Integration page structure

This page shows the recommended structure of an integration page and useful reusable text.

This page outlines the high-level structure of an integration page. Use this structure together with the following documentation:

Basic structure of an integration page​

  • Introduction
    • Use case
  • Supported/unsupported devices
  • Prerequisites
  • Configuration
  • Configuration options
  • Supported functionality
  • Actions
  • Examples
  • Data updates
  • Known limitations
  • Troubleshooting
  • Community notes
  • Removing the integration

Reusable text for integrations​

You can reuse text that's repeated across many pages.

The following snippets are useful for integration pages.

Configuration​

Screenshot showing predefined configuration text block

Screenshot showing the predefined configuration text block

To use this element, add the following line:

{% include integrations/config_flow.md %}

For the current snippet contents, see config_flow.md.

Configuration_basic block​

Use the configuration_basic block to describe configuration options if your integration is set up through a config flow.

Screenshot showing a configuration variable block for integrations that are set up in the UI

Screenshot showing a configuration variable block for integrations that are set up in the UI

{% configuration_basic %}
Host:
    description: "The IP address of your bridge. You can find it in your router or in the Integration app under **Bridge Settings** > **Local API**."
Local access token:
    description: "The local access token for your bridge. You can find it in the Integration app under **Bridge Settings** > **Local API**."
{% endconfiguration_basic %}

Configuration block for YAML integrations​

Use the configuration block to describe configuration options if your integration is set up via YAML only.

Screenshot showing a configuration variable block for YAML integrations

Screenshot showing a configuration variable block for YAML integrations

{% configuration %}
Host:
    description: "The IP address of your bridge. You can find it in your router or in the Integration app under **Bridge Settings** > **Local API**."
    required: false
    type: string
Local access token:
    description: "The local access token for your bridge. You can find it in the Integration app under **Bridge Settings** > **Local API**."
    required: false
    type: string
{% endconfiguration %}