From 35ade923d9e22035b3de151d25e451fd20e1fd97 Mon Sep 17 00:00:00 2001
From: Jan Bouwhuis <jbouwh@users.noreply.github.com>
Date: Tue, 18 Jul 2023 14:30:22 +0200
Subject: [PATCH] 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>
---
 .../alarm_control_panel.mqtt.markdown         | 16 +++---
 .../_integrations/binary_sensor.mqtt.markdown | 16 +++---
 source/_integrations/button.mqtt.markdown     |  8 +--
 source/_integrations/camera.mqtt.markdown     |  4 +-
 source/_integrations/climate.mqtt.markdown    | 12 ++--
 source/_integrations/cover.mqtt.markdown      | 32 +++++------
 .../device_tracker.mqtt.markdown              | 15 ++---
 source/_integrations/fan.mqtt.markdown        | 16 +++---
 source/_integrations/humidifier.mqtt.markdown |  8 +--
 source/_integrations/light.mqtt.markdown      | 56 +++++++++----------
 source/_integrations/lock.mqtt.markdown       |  8 +--
 source/_integrations/mqtt.markdown            | 31 +++++++++-
 source/_integrations/number.mqtt.markdown     |  4 +-
 source/_integrations/scene.mqtt.markdown      | 12 ++--
 source/_integrations/select.mqtt.markdown     | 12 ++--
 source/_integrations/sensor.mqtt.markdown     | 34 +++++------
 source/_integrations/siren.mqtt.markdown      | 12 ++--
 source/_integrations/switch.mqtt.markdown     | 12 ++--
 source/_integrations/text.mqtt.markdown       |  8 +--
 source/_integrations/update.mqtt.markdown     | 16 +++---
 source/_integrations/vacuum.mqtt.markdown     | 12 ++--
 .../_integrations/water_heater.mqtt.markdown  | 12 ++--
 22 files changed, 194 insertions(+), 162 deletions(-)

diff --git a/source/_integrations/alarm_control_panel.mqtt.markdown b/source/_integrations/alarm_control_panel.mqtt.markdown
index 41e2eed10f6..9174c576ba1 100644
--- 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"
diff --git a/source/_integrations/binary_sensor.mqtt.markdown b/source/_integrations/binary_sensor.mqtt.markdown
index 774cd57b645..f4a29f5ac15 100644
--- 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"
diff --git a/source/_integrations/button.mqtt.markdown b/source/_integrations/button.mqtt.markdown
index 0d5775fad8b..3ce21d9281e 100644
--- 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"
diff --git a/source/_integrations/camera.mqtt.markdown b/source/_integrations/camera.mqtt.markdown
index 20f2f5b01da..54e1c82b550 100644
--- 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:
diff --git a/source/_integrations/climate.mqtt.markdown b/source/_integrations/climate.mqtt.markdown
index c8573bc7378..eb04a6c192b 100644
--- 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"
diff --git a/source/_integrations/cover.mqtt.markdown b/source/_integrations/cover.mqtt.markdown
index b7d86c70271..0828c292c7f 100644
--- 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"
diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown
index 24e0a145026..facca931d33 100644
--- a/source/_integrations/device_tracker.mqtt.markdown
+++ b/source/_integrations/device_tracker.mqtt.markdown
@@ -20,11 +20,12 @@ 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"
-    state_topic: "location/annetherese"
-  - name: "paulus_oneplus"
-    state_topic: "location/paulus"
+  - device_tracker:
+      name: "annetherese_n4"
+      state_topic: "location/annetherese"
+  - device_tracker:
+      name: "paulus_oneplus"
+      state_topic: "location/paulus"
 ```
 
 {% configuration %}
@@ -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"
diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown
index a3cf1a7d750..a8c16b60bd9 100644
--- 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') }}"
 ```
diff --git a/source/_integrations/humidifier.mqtt.markdown b/source/_integrations/humidifier.mqtt.markdown
index dbc8c879f12..ee27e70261e 100644
--- 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"
diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown
index f831dfde6e5..9d81d3edc10 100644
--- 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"
diff --git a/source/_integrations/lock.mqtt.markdown b/source/_integrations/lock.mqtt.markdown
index 9d72786e64b..35f01060dce 100644
--- 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"
diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown
index 0836fb8c700..2c9c861a228 100644
--- 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/)
diff --git a/source/_integrations/number.mqtt.markdown b/source/_integrations/number.mqtt.markdown
index 68a1681b7ee..9ddeaf3d52d 100644
--- 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 %}
diff --git a/source/_integrations/scene.mqtt.markdown b/source/_integrations/scene.mqtt.markdown
index 7527096e25a..5c5fa298ab8 100644
--- 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"}'
diff --git a/source/_integrations/select.mqtt.markdown b/source/_integrations/select.mqtt.markdown
index 9cc2fc46b3d..5832fe3e0af 100644
--- a/source/_integrations/select.mqtt.markdown
+++ b/source/_integrations/select.mqtt.markdown
@@ -19,12 +19,12 @@ To enable MQTT Select in your installation, add the following to your `configura
 ```yaml
 # Example configuration.yaml entry
 mqtt:
-  select:
-      - command_topic: topic
-        name: "Test Select"
-        options:
-          - "Option 1"
-          - "Option 2"
+  - select:
+      command_topic: topic
+      name: "Test Select"
+      options:
+        - "Option 1"
+        - "Option 2"
 ```
 
 {% configuration %}
diff --git a/source/_integrations/sensor.mqtt.markdown b/source/_integrations/sensor.mqtt.markdown
index efe8f65c543..e42e2c687b2 100644
--- 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"
 ```
diff --git a/source/_integrations/siren.mqtt.markdown b/source/_integrations/siren.mqtt.markdown
index 96d4e53900f..e514a879607 100644
--- 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"
diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown
index d4d75b48cad..0a9d3be2aae 100644
--- 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"
diff --git a/source/_integrations/text.mqtt.markdown b/source/_integrations/text.mqtt.markdown
index 028c49f8791..11e72fe206e 100644
--- 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"
diff --git a/source/_integrations/update.mqtt.markdown b/source/_integrations/update.mqtt.markdown
index f79f6c67425..5404d402456 100644
--- 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"
@@ -287,8 +287,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"
       value_template: "{{ {'installed_version': value_json.installed_ver, 'latest_version': value_json.new_ver } | to_json }}"
diff --git a/source/_integrations/vacuum.mqtt.markdown b/source/_integrations/vacuum.mqtt.markdown
index d6d75b6248b..ad0062907eb 100644
--- 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
diff --git a/source/_integrations/water_heater.mqtt.markdown b/source/_integrations/water_heater.mqtt.markdown
index e1ecbaa265d..ff679ce68f9 100644
--- 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"