Home AssistantHome AssistantContributors
On this page

This is a Gold rule. In quality_scale.yaml, it is called docs-examples.

The integration page on home-assistant.io shows a few common or useful ways to automate with the integration. Give them as YAML automation examples, or link to a blueprint. Blueprints can live in the source/blueprints/integrations folder of the home-assistant.io repository, or on the blueprint exchange of the forum.

Keep it to a handful. The integration page is not a collection of every automation someone ever wrote.

Why it matters

Examples get users from "it is set up" to "it does something useful". A good example also shows how the entities and actions of the integration fit together, which teaches more than a list of entities can.

Example

Markdown
## Examples

### Turn off the status LEDs at night

The status LEDs of the device are bright. This automation turns them off
at sunset.

{% details "Example YAML configuration" %}

```yaml
automation:
  - alias: "Turn off the status LEDs at sunset"
    triggers:
      - trigger: sun
        event: sunset
    actions:
      - action: switch.turn_off
        target:
          entity_id: switch.my_device_status_led
```

{% enddetails %}

See Write integration documentation and the integration page structure for where this section goes.

How it is checked

Checked in review, usually on the documentation pull request.

Exceptions

Integrations that do not create entities or provide actions, or that only extend a feature of core, like a backup location, are exempt from this rule.

Was this page helpful?

Last updated on .