Introduce new yaml style and update examples (#28229)

* Introduce new yaml style and update examples * Apply suggestions from code review Thnx @frenck ! Co-authored-by: Franck Nijhof <frenck@frenck.nl> --------- Co-authored-by: Franck Nijhof <frenck@frenck.nl>
2025-07-18 23:06:58 +00:00 · 2023-07-18 14:30:22 +02:00 · 2023-07-18 14:30:22 +02:00 · 35ade923d9
commit 35ade923d9
parent ba45d161bb
22 changed files with 194 additions and 162 deletions
--- a/source/_integrations/alarm_control_panel.mqtt.markdown
+++ b/source/_integrations/alarm_control_panel.mqtt.markdown
@ -34,8 +34,8 @@ To enable this platform, add the following lines to your `configuration.yaml`:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  alarm_control_panel:
-    - state_topic: "home/alarm"
+  - alarm_control_panel:
+      state_topic: "home/alarm"
      command_topic: "home/alarm/set"
 ```

@ -267,8 +267,8 @@ The example below shows a full configuration with local code validation.
 ```yaml
 # Example using text based code with local validation configuration.yaml
 mqtt:
-  alarm_control_panel:
-    - name: "Alarm Panel With Numeric Keypad"
+  - alarm_control_panel:
+      name: "Alarm Panel With Numeric Keypad"
      state_topic: "alarmdecoder/panel"
      value_template: "{{value_json.state}}"
      command_topic: "alarmdecoder/panel/set"
@ -286,8 +286,8 @@ The example below shows a full configuration with remote code validation and `co
 ```yaml
 # Example using text code with remote validation configuration.yaml
 mqtt:
-  alarm_control_panel:
-    - name: "Alarm Panel With Text Code Dialog"
+  - alarm_control_panel:
+      name: "Alarm Panel With Text Code Dialog"
      state_topic: "alarmdecoder/panel"
      value_template: "{{ value_json.state }}"
      command_topic: "alarmdecoder/panel/set"
@ -299,8 +299,8 @@ mqtt:
 ```yaml
 # Example using numeric code with remote validation configuration.yaml
 mqtt:
-  alarm_control_panel:
-    - name: "Alarm Panel With Numeric Keypad"
+  - alarm_control_panel:
+      name: "Alarm Panel With Numeric Keypad"
      state_topic: "alarmdecoder/panel"
      value_template: "{{ value_json.state }}"
      command_topic: "alarmdecoder/panel/set"
--- a/source/_integrations/binary_sensor.mqtt.markdown
+++ b/source/_integrations/binary_sensor.mqtt.markdown
@ -27,8 +27,8 @@ add the following to your `configuration.yaml` file:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  binary_sensor:
-    - state_topic: "home-assistant/window/contact"
+  - binary_sensor:
+      state_topic: "home-assistant/window/contact"
 ```

 {% configuration %}
@ -230,8 +230,8 @@ The example below shows a full configuration for a binary sensor:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  binary_sensor:
-    - name: "Window Contact Sensor"
+  - binary_sensor:
+      name: "Window Contact Sensor"
      state_topic: "home-assistant/window/contact"
      payload_on: "ON"
      availability:
@ -252,8 +252,8 @@ mqtt:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  binary_sensor:
-    - state_topic: "lab_button/cmnd/POWER"
+  - binary_sensor:
+      state_topic: "lab_button/cmnd/POWER"
      value_template: "{%if is_state(entity_id,\"on\")-%}OFF{%-else-%}ON{%-endif%}"
 ```

@ -276,8 +276,8 @@ The configuration will look like the example below:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  binary_sensor:
-    - name: Bathroom
+  - binary_sensor:
+      name: Bathroom
      state_topic: "home/bathroom/switch/button"
      payload_on: "1"
      payload_off: "0"
--- a/source/_integrations/button.mqtt.markdown
+++ b/source/_integrations/button.mqtt.markdown
@ -17,8 +17,8 @@ The `mqtt` button platform lets you send an MQTT message when the button is pres
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  button:
-    - command_topic: "home/bedroom/switch1/reboot"
+  - button:
+      command_topic: "home/bedroom/switch1/reboot"
 ```

 {% configuration %}
@ -201,8 +201,8 @@ The example below shows a full configuration for a button.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  button:
-    - unique_id: bedroom_switch_reboot_btn
+  - button:
+      unique_id: bedroom_switch_reboot_btn
      name: "Restart Bedroom Switch"
      command_topic: "home/bedroom/switch1/commands"
      payload_press: "restart"
--- a/source/_integrations/camera.mqtt.markdown
+++ b/source/_integrations/camera.mqtt.markdown
@ -21,8 +21,8 @@ To enable this camera in your installation, add the following to your `configura
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  camera:
-    - topic: zanzito/shared_locations/my-device
+  - camera:
+      topic: zanzito/shared_locations/my-device
 ```

 The sample configuration above can be tested by publishing an image to the topic from the console:
--- a/source/_integrations/climate.mqtt.markdown
+++ b/source/_integrations/climate.mqtt.markdown
@ -19,8 +19,8 @@ To enable this climate platform in your installation, first add the following to
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  climate:
-    - name: Study
+  - climate:
+      name: Study
      mode_command_topic: "study/ac/mode/set"
 ```

@ -431,8 +431,8 @@ Say you receive the operation mode `"auto"` via your `mode_state_topic`, but the

 ```yaml
 mqtt:
-  climate:
-    - name: Study
+  - climate:
+      name: Study
      modes:
        - "off"
        - "heat"
@ -457,8 +457,8 @@ A full configuration example looks like the one below.
 ```yaml
 # Full example configuration.yaml entry
 mqtt:
-  climate:
-    - name: Study
+  - climate:
+      name: Study
      modes:
        - "off"
        - "cool"
--- a/source/_integrations/cover.mqtt.markdown
+++ b/source/_integrations/cover.mqtt.markdown
@ -34,8 +34,8 @@ To use your MQTT cover in your installation, add the following to your `configur
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  cover:
-    - command_topic: "home-assistant/cover/set"
+  - cover:
+      command_topic: "home-assistant/cover/set"
 ```

 {% configuration %}
@ -332,8 +332,8 @@ The example below shows a full configuration for a cover without tilt with state
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  cover:
-    - name: "MQTT Cover"
+  - cover:
+      name: "MQTT Cover"
      command_topic: "home-assistant/cover/set"
      state_topic: "home-assistant/cover/state"
      availability:
@ -364,8 +364,8 @@ The example below shows a full configuration for a cover without tilt with posit
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  cover:
-    - name: "MQTT Cover"
+  - cover:
+      name: "MQTT Cover"
      command_topic: "home-assistant/cover/set"
      position_topic: "home-assistant/cover/position"
      availability:
@ -395,8 +395,8 @@ The example below shows a full configuration for a cover with position, state &
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  cover:
-    - name: "MQTT Cover"
+  - cover:
+      name: "MQTT Cover"
      command_topic: "home-assistant/cover/set"
      state_topic: "home-assistant/cover/state"
      position_topic: "home-assistant/cover/position"
@ -436,8 +436,8 @@ The example below shows a full configuration for a cover using stopped state.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  cover:
-    - name: "MQTT Cover"
+  - cover:
+      name: "MQTT Cover"
      command_topic: "home-assistant/cover/set"
      state_topic: "home-assistant/cover/state"
      position_topic: "home-assistant/cover/position"
@ -470,8 +470,8 @@ Setting `payload_close` empty or to `null` disables the close command and will n
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  cover:
-    - payload_open: "on"
+  - cover:
+      payload_open: "on"
      payload_close: 
      payload_stop: "on"
 ```
@ -505,8 +505,8 @@ The example below shows an example of how to correct the state of the blind depe
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  cover:
-    - name: "MQTT Cover"
+  - cover:
+      name: "MQTT Cover"
      command_topic: "home-assistant/cover/set"
      state_topic: "home-assistant/cover/state"
      position_topic: "home-assistant/cover/position"
@ -549,8 +549,8 @@ Following variable might be used in `position_template`, `set_position_template`
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  cover:
-    - name: "MQTT Cover"
+  - cover:
+      name: "MQTT Cover"
      command_topic: "home-assistant/cover/set"
      state_topic: "home-assistant/cover/state"
      position_topic: "home-assistant/cover/position"
--- a/source/_integrations/device_tracker.mqtt.markdown
+++ b/source/_integrations/device_tracker.mqtt.markdown
@ -20,10 +20,11 @@ To use this device tracker in your installation, add the following to your `conf
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  device_tracker:
-  - name: "annetherese_n4"
+  - device_tracker:
+      name: "annetherese_n4"
      state_topic: "location/annetherese"
-  - name: "paulus_oneplus"
+  - device_tracker:
+      name: "paulus_oneplus"
      state_topic: "location/paulus"
 ```

@ -253,8 +254,8 @@ The following example shows how to configure the same device tracker through con
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  device_tracker:
-    - name: "My Tracker"
+  - device_tracker:
+      name: "My Tracker"
      state_topic: "a4567d663eaf/state"
      payload_home: "home"
      payload_not_home: "not_home"
--- a/source/_integrations/fan.mqtt.markdown
+++ b/source/_integrations/fan.mqtt.markdown
@ -25,8 +25,8 @@ To enable MQTT fans in your installation, add the following to your `configurati
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  fan:
-    - command_topic: "bedroom_fan/on/set"
+  - fan:
+      command_topic: "bedroom_fan/on/set"
 ```

 {% configuration %}
@ -321,8 +321,8 @@ There are 10 speeds within the speed range, so  `percentage_step` = 100 / 10 ste
 ```yaml
 # Example using percentage based speeds with preset modes configuration.yaml
 mqtt:
-  fan:
-    - name: "Bedroom Fan"
+  - fan:
+      name: "Bedroom Fan"
      state_topic: "bedroom_fan/on/state"
      command_topic: "bedroom_fan/on/set"
      direction_state_topic: "bedroom_fan/direction/state"
@ -358,8 +358,8 @@ This example demonstrates how to use command templates with JSON output.
 ```yaml
 # Example configuration.yaml with command templates
 mqtt:
-  fan:
-    - name: "Bedroom Fan"
+  - fan:
+      name: "Bedroom Fan"
      command_topic: "bedroom_fan/on/set"
      command_template: "{ state: '{{ value }}'}"
      direction_command_template: "{{ iif(value == 'forward', 'fwd', 'rev') }}"
@ -387,8 +387,8 @@ This example shows how to configure a fan that doesn't use `forward` and `backwa
 ```yaml
 # Example configuration.yaml with direction templates
 mqtt:
-  fan:
-    - name: "Bedroom Fan"
+  - fan:
+      name: "Bedroom Fan"
      direction_command_template: "{{ iif(value == 'forward', 'fwd', 'rev') }}"
      direction_value_template: "{{ iif(value == 'fwd', 'forward', 'reverse') }}"
 ```
--- a/source/_integrations/humidifier.mqtt.markdown
+++ b/source/_integrations/humidifier.mqtt.markdown
@ -25,8 +25,8 @@ To enable MQTT humidifiers in your installation, add the following to your `conf
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  humidifier:
-    - command_topic: "bedroom_humidifier/on/set"
+  - humidifier:
+      command_topic: "bedroom_humidifier/on/set"
      target_humidity_command_topic: "bedroom_humidifier/humidity/set"
 ```

@ -304,8 +304,8 @@ The example below shows a full configuration for a MQTT humidifier including mod
 ```yaml
 # Example configuration.yaml
 mqtt:
-  humidifier:
-    - name: "Bedroom humidifier"
+  - humidifier:
+      name: "Bedroom humidifier"
      device_class: "humidifier"
      state_topic: "bedroom_humidifier/on/state"
      action_topic: "bedroom_humidifier/action"
--- a/source/_integrations/light.mqtt.markdown
+++ b/source/_integrations/light.mqtt.markdown
@ -47,8 +47,8 @@ The state of MQTT lights with default schema and support for both color and colo
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - command_topic: "office/rgb1/light/switch"
+  - light:
+      command_topic: "office/rgb1/light/switch"
 ```

 {% configuration %}
@ -419,8 +419,8 @@ To enable a light with brightness and RGB support in your installation, add the
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - name: "Office Light RGB"
+  - light:
+      name: "Office Light RGB"
      state_topic: "office/rgb1/light/status"
      command_topic: "office/rgb1/light/switch"
      brightness_state_topic: "office/rgb1/brightness/status"
@ -445,8 +445,8 @@ To enable a light with brightness (no RGB version) in your installation, add the
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - name: "Office light"
+  - light:
+      name: "Office light"
      state_topic: "office/light/status"
      command_topic: "office/light/switch"
      brightness_state_topic: 'office/light/brightness'
@ -464,8 +464,8 @@ To enable a light that sends only brightness topics to turn it on, add the follo
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - name: "Brightness light"
+  - light:
+      name: "Brightness light"
      state_topic: "office/light/status"
      command_topic: "office/light/switch"
      payload_off: "OFF"
@ -519,8 +519,8 @@ Optimistic mode can be forced, even if state topic is available. Try enabling it
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: json
+  - light:
+      schema: json
      command_topic: "home/rgb1/set"
 ```

@ -748,8 +748,8 @@ To enable a light with brightness and RGB support in your installation, add the
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: json
+  - light:
+      schema: json
      name: mqtt_json_light_1
      state_topic: "home/rgb1"
      command_topic: "home/rgb1/set"
@ -765,8 +765,8 @@ To enable a light with brightness (but no color support) in your installation, a
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: json
+  - light:
+      schema: json
      name: mqtt_json_light_1
      state_topic: "home/rgb1"
      command_topic: "home/rgb1/set"
@ -782,8 +782,8 @@ To enable a light using a brightness scale other than 8bit the `brightness_scale
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: json
+  - light:
+      schema: json
      name: mqtt_json_light_1
      state_topic: "home/light"
      command_topic: "home/light/set"
@ -808,8 +808,8 @@ To use a light with hue+saturation as the color model, set `supported_color_mode

 ```yaml
 mqtt:
-  light:
-    - schema: json
+  - light:
+      schema: json
      name: mqtt_json_hs_light
      state_topic: "home/light"
      command_topic: "home/light/set"
@ -837,8 +837,8 @@ To enable a light with brightness, RGB support and a separate white channel (RGB
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: json
+  - light:
+      schema: json
      name: mqtt_json_light_1
      state_topic: "home/rgbw1"
      command_topic: "home/rgbw1/set"
@ -881,8 +881,8 @@ Optimistic mode can be forced, even if state topic is available. Try enabling it
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: template
+  - light:
+      schema: template
      command_topic: "home/rgb1/set"
      command_on_template: "on"
      command_off_template: "off"
@ -1100,8 +1100,8 @@ For a simple string payload with the format `state,brightness,r-g-b,h-s` (e.g.,
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: template
+  - light:
+      schema: template
      command_topic: "home/rgb1/set"
      state_topic: "home/rgb1/status"
      command_on_template: "on,{{ brightness|d }},{{ red|d }}-{{ green|d }}-{{ blue|d }},{{ hue|d }}-{{ sat|d }}"
@ -1124,8 +1124,8 @@ For a JSON payload with the format `{"state": "on", "brightness": 255, "color":
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: template
+  - light:
+      schema: template
      effect_list:
        - rainbow
        - colorloop
@ -1169,8 +1169,8 @@ Add the following to your `configuration.yaml` file:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  light:
-    - schema: template
+  - light:
+      schema: template
      name: "Bulb-white"
      command_topic: "shellies/bulb/color/0/set"
      state_topic: "shellies/bulb/color/0/status"
--- a/source/_integrations/lock.mqtt.markdown
+++ b/source/_integrations/lock.mqtt.markdown
@ -28,8 +28,8 @@ To enable MQTT locks in your installation, add the following to your `configurat
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  lock:
-    - command_topic: "home/frontdoor/set"
+  - lock:
+      command_topic: "home/frontdoor/set"
 ```

 {% configuration %}
@ -260,8 +260,8 @@ The example below shows a full configuration for a MQTT lock.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  lock:
-    - name: Frontdoor
+  - lock:
+      name: Frontdoor
      state_topic: "home-assistant/frontdoor/state"
      code_format: "^\\d{4}$"
      command_topic: "home-assistant/frontdoor/set"
--- a/source/_integrations/mqtt.markdown
+++ b/source/_integrations/mqtt.markdown
@ -679,7 +679,36 @@ In the example above, the entity_id will be `sensor.my_super_device` instead of

 For most integrations, it is also possible to manually set up MQTT items in `configuration.yaml`. Read more [about configuration in YAML](/docs/configuration/yaml).

-{% details "MQTT integrations that support setup via YAML" %}
+MQTT supports two styles for configuring items in YAML. All configuration items are placed directly under the `mqtt` integration key. Note that you cannot mix these styles. Use the *YAML configuration listed per item* style when in doubt.
+
+### YAML configuration listed per item
+
+This method expects all items to be in a YAML list. Each item has a `{domain}` key and the item config is placed directly under the domain key. This method is considered as best practice. In all the examples we use this format.
+
+```yaml
+mqtt:
+  - {domain}:
+      name: ""
+      ...
+  - {domain}:
+      name: ""
+      ...
+```
+
+### YAML configuration keyed and bundled by `{domain}`
+
+All items are grouped per `{domain}` and where all configs are listed.
+
+```yaml
+mqtt:
+  {domain}:
+    - name: ""
+      ...
+    - name: ""
+      ...
+```
+
+{% details "MQTT components that support setup via YAML" %}

 - [Alarm control panel](/integrations/alarm_control_panel.mqtt/)
 - [Binary sensor](/integrations/binary_sensor.mqtt/)
--- a/source/_integrations/number.mqtt.markdown
+++ b/source/_integrations/number.mqtt.markdown
@ -19,8 +19,8 @@ To enable MQTT Number in your installation, add the following to your `configura
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  number:
-    - command_topic: my-device/threshold
+  - number:
+      command_topic: my-device/threshold
 ```

 {% configuration %}
--- a/source/_integrations/scene.mqtt.markdown
+++ b/source/_integrations/scene.mqtt.markdown
@ -19,8 +19,8 @@ To enable a MQTT scene in your installation, add the following to your `configur
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  scene:
-    - command_topic: zigbee2mqtt/living_room_group/set
+  - scene:
+      command_topic: zigbee2mqtt/living_room_group/set
 ```

 {% configuration %}
@ -135,8 +135,8 @@ The example below shows a full configuration for a scene.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  scene:
-    - unique_id: living_room_party_scene
+  - scene:
+      unique_id: living_room_party_scene
      name: "Living Room Party Scene"
      command_topic: "home/living_room/party_scene/set"
      availability:
@ -153,8 +153,8 @@ The example below shows a configuration using a JSON payload.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  scene:
-    - name: Living Room Blue Scene
+  - scene:
+      name: Living Room Blue Scene
      unique_id: living_room_blue_scene
      command_topic: "home/living_room/set"
      payload_on: '{"activate_scene": "Blue Scene"}'
--- a/source/_integrations/select.mqtt.markdown
+++ b/source/_integrations/select.mqtt.markdown
@ -19,8 +19,8 @@ To enable MQTT Select in your installation, add the following to your `configura
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  select:
-      - command_topic: topic
+  - select:
+      command_topic: topic
      name: "Test Select"
      options:
        - "Option 1"
--- a/source/_integrations/sensor.mqtt.markdown
+++ b/source/_integrations/sensor.mqtt.markdown
@ -19,8 +19,8 @@ To use your MQTT sensor in your installation, add the following to your `configu
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  sensor:
-    - state_topic: "home/bedroom/temperature"
+  - sensor:
+      state_topic: "home/bedroom/temperature"
 ```

 {% configuration %}
@ -220,8 +220,8 @@ Extra attributes will be displayed in the frontend and can also be extracted in
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  sensor:
-    - name: "RSSI"
+  - sensor:
+      name: "RSSI"
      state_topic: "home/sensor1/infojson"
      unit_of_measurement: "dBm"
      value_template: "{{ value_json.RSSI }}"
@ -245,13 +245,14 @@ Extra attributes will be displayed in the frontend and can also be extracted in
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  sensor:
-    - name: "Timer 1"
+  - sensor:
+      name: "Timer 1"
      state_topic: "tele/sonoff/sensor"
      value_template: "{{ value_json.Timer1.Arm }}"
      json_attributes_topic: "tele/sonoff/sensor"
      json_attributes_template: "{{ value_json.Timer1 | tojson }}"
-    - name: "Timer 2"
+  - sensor:
+      name: "Timer 2"
      state_topic: "tele/sonoff/sensor"
      value_template: "{{ value_json.Timer2.Arm }}"
      json_attributes_topic: "tele/sonoff/sensor"
@ -271,8 +272,8 @@ The example below shows how a simple filter, that calculates the value by adding
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  sensor:
-    - name: "Temp 1"
+  - sensor:
+      name: "Temp 1"
      state_topic: "sensor/temperature"
      value_template: |-
        {% if states(entity_id) == None %}
@ -299,8 +300,8 @@ Thus the trick is extracting the battery level from the payload.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  sensor:
-    - name: "Battery Tablet"
+  - sensor:
+      name: "Battery Tablet"
      state_topic: "owntracks/tablet/tablet"
      unit_of_measurement: "%"
      value_template: "{{ value_json.batt }}"
@ -327,13 +328,14 @@ Then use this configuration example to extract the data from the payload:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  sensor:
-    - name: "Temperature"
+  - sensor:
+      name: "Temperature"
      state_topic: "office/sensor1"
      suggested_display_precision: 1
      unit_of_measurement: "°C"
      value_template: "{{ value_json.temperature }}"
-    - name: "Humidity"
+  - sensor:
+      name: "Humidity"
      state_topic: "office/sensor1"
      unit_of_measurement: "%"
      value_template: "{{ value_json.humidity }}"
@ -363,7 +365,7 @@ The configuration will look like the example below:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  sensor:
-    - name: "Brightness"
+  - sensor:
+      name: "Brightness"
      state_topic: "home/bathroom/analog/brightness"
 ```
--- a/source/_integrations/siren.mqtt.markdown
+++ b/source/_integrations/siren.mqtt.markdown
@ -25,8 +25,8 @@ To enable this siren in your installation, add the following to your `configurat
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  siren:
-    - command_topic: "home/bedroom/siren/set"
+  - siren:
+      command_topic: "home/bedroom/siren/set"
 ```

 {% configuration %}
@ -252,8 +252,8 @@ The example below shows a full configuration for a siren.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  siren:
-    - unique_id: custom_siren
+  - siren:
+      unique_id: custom_siren
      name: "Intrusion siren"
      state_topic: "home/alarm/siren1"
      command_topic: "home/alarm/siren1/set"
@ -282,8 +282,8 @@ The example below shows a configuration for an On/Off type siren, which does not
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  siren:
-    - unique_id: tasmota_siren
+  - siren:
+      unique_id: tasmota_siren
      name: "garage"
      state_topic: "stat/SIREN/RESULT"
      command_topic: "cmnd/SIREN/POWER"
--- a/source/_integrations/switch.mqtt.markdown
+++ b/source/_integrations/switch.mqtt.markdown
@ -25,8 +25,8 @@ To enable this switch in your installation, add the following to your `configura
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  switch:
-    - command_topic: "home/bedroom/switch1/set"
+  - switch:
+      command_topic: "home/bedroom/switch1/set"
 ```

 {% configuration %}
@ -232,8 +232,8 @@ The example below shows a full configuration for a switch.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  switch:
-    - unique_id: bedroom_switch
+  - switch:
+      unique_id: bedroom_switch
      name: "Bedroom Switch"
      state_topic: "home/bedroom/switch1"
      command_topic: "home/bedroom/switch1/set"
@ -269,8 +269,8 @@ The configuration will look like the example below:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  switch:
-    - name: bathroom
+  - switch:
+      name: bathroom
      state_topic: "home/bathroom/gpio/13"
      command_topic: "home/bathroom/gpio/13"
      payload_on: "1"
--- a/source/_integrations/text.mqtt.markdown
+++ b/source/_integrations/text.mqtt.markdown
@ -17,8 +17,8 @@ To enable MQTT text platform in your installation, add the following to your `co
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  text:
-    - command_topic: command-topic
+  - text:
+      command_topic: command-topic
 ```

 {% configuration %}
@ -201,8 +201,8 @@ This is an example of a manual configured MQTT `text` item.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  text:
-    - name: "Remote LCD screen"
+  - text:
+      name: "Remote LCD screen"
      icon: mdi:ab-testing
      mode: "text"
      command_topic: "txt/cmd"
--- a/source/_integrations/update.mqtt.markdown
+++ b/source/_integrations/update.mqtt.markdown
@ -17,8 +17,8 @@ To enable MQTT Update in your installation, add the following to your `configura
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  update:
-    - state_topic: topic-installed
+  - update:
+      state_topic: topic-installed
      latest_version_topic: topic-latest
 ```

@ -216,8 +216,8 @@ This is an example of Update entity configuration for Shelly Gen1 device.
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  update:
-    - name: "Shelly Plug S Firmware Update"
+  - update:
+      name: "Shelly Plug S Firmware Update"
      title: "Shelly Plug S Firmware"
      release_url: "https://shelly-api-docs.shelly.cloud/gen1/#changelog"
      entity_picture: "https://brands.home-assistant.io/_/shelly/icon.png"
@ -256,8 +256,8 @@ For the above JSON payload, the `update` entity configuration should look like t
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  update:
-    - name: "Amazing Device Update"
+  - update:
+      name: "Amazing Device Update"
      title: "Device Firmware"
      state_topic: "amazing-device/state-topic"
      device_class: "firmware"
@ -288,7 +288,7 @@ For the above JSON payload, the `update` entity configuration should look like t
 # Example configuration.yaml entry
 mqtt:
   update:
-    - name: "Amazing Device Update"
+      name: "Amazing Device Update"
      title: "Device Firmware"
      state_topic: "amazing-device/state-topic"
      value_template: "{{ {'installed_version': value_json.installed_ver, 'latest_version': value_json.new_ver } | to_json }}"
--- a/source/_integrations/vacuum.mqtt.markdown
+++ b/source/_integrations/vacuum.mqtt.markdown
@ -24,8 +24,8 @@ To add your MQTT vacuum to your installation, add the following to your `configu
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  vacuum:
-    - command_topic: "vacuum/command"
+  - vacuum:
+      command_topic: "vacuum/command"
 ```

 ## Legacy Configuration
@ -247,8 +247,8 @@ unique_id:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  vacuum:
-    - name: "MQTT Vacuum"
+  - vacuum:
+      name: "MQTT Vacuum"
      supported_features:
        - turn_on
        - turn_off
@ -520,8 +520,8 @@ unique_id:
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  vacuum:
-    - name: "MQTT Vacuum"
+  - vacuum:
+      name: "MQTT Vacuum"
      schema: state
      supported_features:
        - start
--- a/source/_integrations/water_heater.mqtt.markdown
+++ b/source/_integrations/water_heater.mqtt.markdown
@ -19,8 +19,8 @@ To enable this water heater platform in your installation, first add the followi
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  water_heater:
-    - name: Boiler
+  - water_heater:
+      name: Boiler
      mode_command_topic: "basement/boiler/mode/set"
 ```

@ -267,8 +267,8 @@ Say you receive the operation mode `"off"` via your `mode_state_topic`, but the

 ```yaml
 mqtt:
-  water_heater:
-    - name: Boiler
+  - water_heater:
+      name: Boiler
      modes:
        - "off"
        - "eco"
@ -293,8 +293,8 @@ A full configuration example looks like the one below.
 ```yaml
 # Full example configuration.yaml entry
 mqtt:
-  water_heater:
-    - name: Boiler
+  - water_heater:
+      name: Boiler
      modes:
        - "off"
        - "eco"