MQTT Manual config items under integration key Fan and Light platform (#22805)

source/_integrations/fan.mqtt.markdown

@@ -22,11 +22,30 @@ 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"
+```
+
+<a id='new_format'></a>
+
+{% details "Previous configuration format" %}
+
+The configuration format of manual configured MQTT items has changed.
+The old format that places configurations under the `fan` platform key
+should no longer be used and is deprecated.
+
+The above example shows the new and modern way,
+this is the previous/old example:
+
+```yaml
 fan:
-  - platform: mqtt
+  - platform: "mqtt"
     command_topic: "bedroom_fan/on/set"
 ```
 
+{% enddetails %}
+
 {% configuration %}
 availability:
   description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
@@ -298,9 +317,9 @@ 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
-fan:
+mqtt:
-  - platform: mqtt
+  fan:
-    name: "Bedroom Fan"
+    - name: "Bedroom Fan"
       state_topic: "bedroom_fan/on/state"
       command_topic: "bedroom_fan/on/set"
       oscillation_state_topic: "bedroom_fan/oscillation/state"
@@ -332,9 +351,9 @@ This example demonstrates how to use command templates with JSON output.
 
 ```yaml
 # Example configuration.yaml with command templates
-fan:
+mqtt:
-  - platform: mqtt
+  fan:
-    name: "Bedroom Fan"
+    - name: "Bedroom Fan"
       command_topic: "bedroom_fan/on/set"
       command_template: "{ state: '{{ value }}'}"
       oscillation_command_topic: "bedroom_fan/oscillation/set"

source/_integrations/light.mqtt.markdown

@@ -27,7 +27,6 @@ The `mqtt` light platform lets you control your MQTT enabled lights through one
 | White             | ✔                            | ✔                      | ✘                              |
 | XY Color          | ✔                            | ✔                      | ✘                              |
 
-
 ## Default schema
 
 The `mqtt` light platform with default schema lets you control your MQTT enabled lights. It supports setting brightness, color temperature, effects, on/off, RGB colors, XY colors and white.
@@ -45,11 +44,30 @@ 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"
+```
+
+<a id='new_format'></a>
+
+{% details "Previous configuration format" %}
+
+The configuration format of manual configured MQTT items has changed.
+The old format that places configurations under the `light` platform key
+should no longer be used and is deprecated.
+
+The above example shows the new and modern way,
+this is the previous/old example:
+
+```yaml
 light:
-  - platform: mqtt
+  - platform: "mqtt"
     command_topic: "office/rgb1/light/switch"
 ```
 
+{% enddetails %}
+
 {% configuration %}
 availability:
   description: A list of MQTT topics subscribed to receive availability (online/offline) updates. Must not be used together with `availability_topic`.
@@ -405,9 +423,9 @@ To enable a light with brightness and RGB support in your installation, add the
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    name: "Office Light RGB"
+    - name: "Office Light RGB"
       state_topic: "office/rgb1/light/status"
       command_topic: "office/rgb1/light/switch"
       brightness_state_topic: "office/rgb1/brightness/status"
@@ -431,9 +449,9 @@ To enable a light with brightness (no RGB version) in your installation, add the
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    name: "Office light"
+    - name: "Office light"
       state_topic: "office/light/status"
       command_topic: "office/light/switch"
       brightness_state_topic: 'office/light/brightness'
@@ -450,9 +468,9 @@ To enable a light that sends only brightness topics to turn it on, add the follo
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    name: "Brightness light"
+    - name: "Brightness light"
       state_topic: "office/light/status"
       command_topic: "office/light/switch"
       payload_off: "OFF"
@@ -503,11 +521,15 @@ When a state topic is not available, the light will work in optimistic mode. In
 
 Optimistic mode can be forced, even if state topic is available. Try enabling it if the light is operating incorrectly.
 
+<div class='note warning'>
+The way manual MQTT Fans are configured has changed. Placing configurations under the `fan` platform key is deprecated.
+</div>
+
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: json
+    - schema: json
       command_topic: "home/rgb1/set"
 ```
 
@@ -729,9 +751,9 @@ To enable a light with brightness and RGB support in your installation, add the
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: json
+    - schema: json
       name: mqtt_json_light_1
       state_topic: "home/rgb1"
       command_topic: "home/rgb1/set"
@@ -746,9 +768,9 @@ To enable a light with brightness (but no color support) in your installation, a
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: json
+    - schema: json
       name: mqtt_json_light_1
       state_topic: "home/rgb1"
       command_topic: "home/rgb1/set"
@@ -760,11 +782,12 @@ light:
 ### Brightness Scaled
 
 To enable a light using a brightness scale other than 8bit the `brightness_scale` option may be added to denote the "fully on" value:
+
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: json
+    - schema: json
       name: mqtt_json_light_1
       state_topic: "home/light"
       command_topic: "home/light/set"
@@ -788,9 +811,9 @@ Home Assistant will then convert its 8bit value in the message to and from the d
 To use a light with hue+saturation as the color model, set `supported_color_modes` to `["hs"]` in the platform configuration:
 
 ```yaml
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: json
+    - schema: json
       name: mqtt_json_hs_light
       state_topic: "home/light"
       command_topic: "home/light/set"
@@ -817,9 +840,9 @@ To enable a light with brightness, RGB support and a separate white channel (RGB
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: json
+    - schema: json
       name: mqtt_json_light_1
       state_topic: "home/rgbw1"
       command_topic: "home/rgbw1/set"
@@ -828,7 +851,6 @@ light:
       supported_color_modes: ["rgbw"]
 ```
 
-
 ## Implementations
 
 - A full example of custom lighting using this platform and an ESP8266 microcontroller can be found [here](https://github.com/corbanmailloux/esp-mqtt-rgb-led). It supports on/off, brightness, transitions, RGB colors, and flashing.
@@ -862,9 +884,9 @@ Optimistic mode can be forced, even if state topic is available. Try enabling it
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: template
+    - schema: template
       command_topic: "home/rgb1/set"
       command_on_template: "on"
       command_off_template: "off"
@@ -1081,9 +1103,9 @@ For a simple string payload with the format `state,brightness,r-g-b,h-s` (e.g.,
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: template
+    - 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 }}"
@@ -1105,9 +1127,9 @@ For a JSON payload with the format `{"state": "on", "brightness": 255, "color":
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: template
+    - schema: template
       effect_list:
         - rainbow
         - colorloop
@@ -1150,9 +1172,9 @@ Add the following to your `configuration.yaml` file:
 
 ```yaml
 # Example configuration.yaml entry
-light:
+mqtt:
-  - platform: mqtt
+  light:
-    schema: template
+    - schema: template
       name: "Bulb-white"
       command_topic: "shellies/bulb/color/0/set"
       state_topic: "shellies/bulb/color/0/status"