diff --git a/source/_docs/mqtt.markdown b/source/_docs/mqtt.markdown
deleted file mode 100644
index 980afb7922d..00000000000
--- a/source/_docs/mqtt.markdown
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "MQTT"
-description: "Details about the MQTT support of Home Assistant."
----
-
-MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things" connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport.
-
-To integrate MQTT into Home Assistant, you need to setup the [MQTT integration](/integrations/mqtt).
-
-You will also need to setup an MQTT broker, please refer to the [MQTT broker](/docs/mqtt/broker) documentation.
-
-## Additional features
-
-- [Certificate](/docs/mqtt/certificate/)
-- [Discovery](/docs/mqtt/discovery/)
-- [Publish service](/docs/mqtt/service/)
-- [Birth and last will messages](/docs/mqtt/birth_will/)
-- [Testing your setup](/docs/mqtt/testing/)
-- [Logging](/docs/mqtt/logging/)
diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html
index 7fa5b627746..c70bc53be07 100644
--- a/source/_includes/asides/docs_navigation.html
+++ b/source/_includes/asides/docs_navigation.html
@@ -155,18 +155,18 @@
- {% active_link /docs/mqtt/ MQTT %}
+ {% active_link /integrations/mqtt MQTT %}
- - {% active_link /docs/mqtt/broker/ Broker %}
- - {% active_link /docs/mqtt/certificate/ Certificate %}
- - {% active_link /docs/mqtt/discovery/ Discovery %}
- - {% active_link /docs/mqtt/service/ Publish service %}
+ - {% active_link /integrations/mqtt/#broker-configuration Broker %}
+ - {% active_link /integrations/mqtt/#advanced-broker-configuration Certificate %}
+ - {% active_link /integrations/mqtt/#mqtt-discovery Discovery %}
+ - {% active_link /integrations/mqtt/#publish--dump-services Publish service %}
-
- {% active_link /docs/mqtt/birth_will/ Birth and last will messages
+ {% active_link /integrations/mqtt/#birth-and-last-will-messages Birth and last will messages
%}
- - {% active_link /docs/mqtt/testing/ Testing your setup %}
- - {% active_link /docs/mqtt/logging/ Logging %}
+ - {% active_link /integrations/mqtt/#testing-your-setup Testing your setup %}
+ - {% active_link /integrations/mqtt/#logging Logging %}
diff --git a/source/_integrations/alarm_control_panel.mqtt.markdown b/source/_integrations/alarm_control_panel.mqtt.markdown
index 93795eab5ed..3c1831923fe 100644
--- a/source/_integrations/alarm_control_panel.mqtt.markdown
+++ b/source/_integrations/alarm_control_panel.mqtt.markdown
@@ -105,7 +105,7 @@ command_topic:
required: true
type: string
device:
- description: "Information about the device this alarm panel is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this alarm panel is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/ambient_station.markdown b/source/_integrations/ambient_station.markdown
index 70428198971..a50ffb41a1f 100644
--- a/source/_integrations/ambient_station.markdown
+++ b/source/_integrations/ambient_station.markdown
@@ -55,4 +55,4 @@ Cloud. Users desiring a local option are encouraged to explore the
[Ecowitt](https://www.ecowitt.com) family of devices, which are able to read RF signals
directly from the PWS and transmit them to a variety of other applications, including
[`ecowitt2mqtt`](https://github.com/bachya/ecowitt2mqtt) (which supports
-[MQTT Discovery](/docs/mqtt/discovery)), or the built-in [Ecowitt](/integrations/ecowitt/) integration.
+[MQTT Discovery](/integrations/mqtt/#mqtt-discovery)), or the built-in [Ecowitt](/integrations/ecowitt/) integration.
diff --git a/source/_integrations/binary_sensor.mqtt.markdown b/source/_integrations/binary_sensor.mqtt.markdown
index d976b7023d9..e4a13a4cea5 100644
--- a/source/_integrations/binary_sensor.mqtt.markdown
+++ b/source/_integrations/binary_sensor.mqtt.markdown
@@ -69,7 +69,7 @@ availability_topic:
required: false
type: string
device:
- description: "Information about the device this binary sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this binary sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/button.mqtt.markdown b/source/_integrations/button.mqtt.markdown
index 7a0610f6c59..f4dbf214ff3 100644
--- a/source/_integrations/button.mqtt.markdown
+++ b/source/_integrations/button.mqtt.markdown
@@ -67,7 +67,7 @@ command_topic:
required: false
type: string
device:
- description: "Information about the device this button is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this button is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/camera.mqtt.markdown b/source/_integrations/camera.mqtt.markdown
index 1a470370a50..fcbb274b3c6 100644
--- a/source/_integrations/camera.mqtt.markdown
+++ b/source/_integrations/camera.mqtt.markdown
@@ -69,7 +69,7 @@ availability_topic:
required: false
type: string
device:
- description: "Information about the device this camera is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this camera is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/climate.mqtt.markdown b/source/_integrations/climate.mqtt.markdown
index 6678eaef9e2..4754c3a4c06 100644
--- a/source/_integrations/climate.mqtt.markdown
+++ b/source/_integrations/climate.mqtt.markdown
@@ -92,7 +92,7 @@ current_temperature_topic:
required: false
type: string
device:
- description: 'Information about the device this HVAC device is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
+ description: 'Information about the device this HVAC device is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
type: map
keys:
diff --git a/source/_integrations/cover.mqtt.markdown b/source/_integrations/cover.mqtt.markdown
index e0d0054d394..c5a2d5d4039 100644
--- a/source/_integrations/cover.mqtt.markdown
+++ b/source/_integrations/cover.mqtt.markdown
@@ -80,7 +80,7 @@ command_topic:
required: false
type: string
device:
- description: "Information about the device this cover is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this cover is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown
index 3c507ca4130..e4de2edc032 100644
--- a/source/_integrations/device_tracker.mqtt.markdown
+++ b/source/_integrations/device_tracker.mqtt.markdown
@@ -181,7 +181,7 @@ value_template:
### Using the discovery protocol
-The device_tracker can be created via publishing to a discovery topic that follows the following [MQTT Discovery](/docs/mqtt/discovery/#discovery-topic) topic name format: `/device_tracker/[/]/config`.
+The device_tracker can be created via publishing to a discovery topic that follows the following [MQTT Discovery](/integrations/mqtt/#mqtt-discovery#discovery-topic) topic name format: `/device_tracker/[/]/config`.
You can use the command line tool `mosquitto_pub` shipped with `mosquitto` or the `mosquitto-clients` package to send MQTT messages.
diff --git a/source/_integrations/device_trigger.mqtt.markdown b/source/_integrations/device_trigger.mqtt.markdown
index 3388eada90a..bb821100905 100644
--- a/source/_integrations/device_trigger.mqtt.markdown
+++ b/source/_integrations/device_trigger.mqtt.markdown
@@ -14,7 +14,7 @@ An MQTT device trigger is a better option than a [binary sensor](/integrations/b
## Configuration
-MQTT device triggers are only supported through [MQTT discovery](/docs/mqtt/discovery/), manual setup through `configuration.yaml` is not supported.
+MQTT device triggers are only supported through [MQTT discovery](/integrations/mqtt/#mqtt-discovery), manual setup through `configuration.yaml` is not supported.
The discovery topic needs to be: `/device_automation/[/]/config`. Note that only one trigger may be defined per unique discovery topic. Also note that the combination of `type` and `subtype` should be unique for a device.
{% configuration %}
diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown
index e9996c7bdff..e827fcae75c 100644
--- a/source/_integrations/fan.mqtt.markdown
+++ b/source/_integrations/fan.mqtt.markdown
@@ -75,7 +75,7 @@ command_topic:
required: true
type: string
device:
- description: "Information about the device this fan is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this fan is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/humidifier.mqtt.markdown b/source/_integrations/humidifier.mqtt.markdown
index 30363d7c8c2..8921ff1f731 100644
--- a/source/_integrations/humidifier.mqtt.markdown
+++ b/source/_integrations/humidifier.mqtt.markdown
@@ -76,7 +76,7 @@ command_topic:
required: true
type: string
device:
- description: "Information about the device this humidifier is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this humidifier is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown
index 8d0a90bca0d..e5719781036 100644
--- a/source/_integrations/light.mqtt.markdown
+++ b/source/_integrations/light.mqtt.markdown
@@ -138,7 +138,7 @@ command_topic:
required: true
type: string
device:
- description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
+ description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
type: map
keys:
@@ -573,7 +573,7 @@ command_topic:
required: true
type: string
device:
- description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
+ description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
type: map
keys:
@@ -847,11 +847,11 @@ mqtt:
- [McLighting](https://github.com/toblum/McLighting) is another ESP8266 firmware for WS2812 addressable LEDs.
-- [MQTT JSON Light](https://github.com/mertenats/Open-Home-Automation/tree/master/ha_mqtt_rgbw_light_with_discovery) is another implementation for ESP8266 including [MQTT discovery](/docs/mqtt/discovery/).
+- [MQTT JSON Light](https://github.com/mertenats/Open-Home-Automation/tree/master/ha_mqtt_rgbw_light_with_discovery) is another implementation for ESP8266 including [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
-- [ESPHome](https://esphome.io) implements the JSON schema for MQTT based installs and supports [MQTT discovery](/docs/mqtt/discovery/).
+- [ESPHome](https://esphome.io) implements the JSON schema for MQTT based installs and supports [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
-- [AiLight](https://github.com/stelgenhof/AiLight) is a custom firmware for the Ai-Thinker (and equivalent) RGBW WiFi light bulbs that has an ESP8266 onboard and controlled by the MY9291 LED driver. It implements the [MQTT JSON light](/integrations/light.mqtt) platform and supports ON/OFF, RGBW colours, brightness, color temperature, flashing and transitions. Also it includes [MQTT Auto Discovery](/docs/mqtt/discovery/)) and the MQTT Last Will and Testament is enabled as well.
+- [AiLight](https://github.com/stelgenhof/AiLight) is a custom firmware for the Ai-Thinker (and equivalent) RGBW WiFi light bulbs that has an ESP8266 onboard and controlled by the MY9291 LED driver. It implements the [MQTT JSON light](/integrations/light.mqtt) platform and supports ON/OFF, RGBW colours, brightness, color temperature, flashing and transitions. Also it includes [MQTT Auto Discovery](/integrations/mqtt/#mqtt-discovery)) and the MQTT Last Will and Testament is enabled as well.
- [h801-mqtt-json](https://github.com/starkillerOG/h801-mqtt-json) is a custom firmware for the H801 LED dimmer, a 5 channel (RGBWWCW) WiFi LED strip controller for 12V LED strips. The firmware is meant to control the 5 channels of the H801 to simultaneously control an RGB and a Warm-white/Cold-white LED strip such as a 5050 RGB LED strip and a 5025 Dual White strip. It implements the [MQTT JSON light](/integrations/light.mqtt) platform and supports ON/OFF, RGBW colours (RGB strip), brightness, color temperature (CW/WW strip) and transitions.
@@ -942,7 +942,7 @@ command_topic:
required: true
type: string
device:
- description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
+ description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
type: map
keys:
diff --git a/source/_integrations/lock.mqtt.markdown b/source/_integrations/lock.mqtt.markdown
index deb83f550fd..d8e2bc2c84f 100644
--- a/source/_integrations/lock.mqtt.markdown
+++ b/source/_integrations/lock.mqtt.markdown
@@ -73,7 +73,7 @@ command_topic:
required: true
type: string
device:
- description: 'Information about the device this lock is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
+ description: 'Information about the device this lock is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
type: map
keys:
diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown
index 0510dd793da..e567a2e5b8d 100644
--- a/source/_integrations/mqtt.markdown
+++ b/source/_integrations/mqtt.markdown
@@ -559,7 +559,7 @@ Delete the sensor by sending an empty message.
mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m ''
```
-For more details please refer to the [MQTT testing section](/docs/mqtt/testing/).
+For more details please refer to the [MQTT testing section](/integrations/mqtt/#testing-your-setup).
#### Sensors
diff --git a/source/_integrations/number.mqtt.markdown b/source/_integrations/number.mqtt.markdown
index 686f4c20c10..5dbcb101c92 100644
--- a/source/_integrations/number.mqtt.markdown
+++ b/source/_integrations/number.mqtt.markdown
@@ -61,7 +61,7 @@ command_topic:
required: true
type: string
device:
- description: "Information about the device this Number is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this Number is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/select.mqtt.markdown b/source/_integrations/select.mqtt.markdown
index b59db985df8..15e403902e6 100644
--- a/source/_integrations/select.mqtt.markdown
+++ b/source/_integrations/select.mqtt.markdown
@@ -73,7 +73,7 @@ command_topic:
required: true
type: string
device:
- description: "Information about the device this Select is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this Select is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/sensor.mqtt.markdown b/source/_integrations/sensor.mqtt.markdown
index e00637a445c..7ab82ff789a 100644
--- a/source/_integrations/sensor.mqtt.markdown
+++ b/source/_integrations/sensor.mqtt.markdown
@@ -61,7 +61,7 @@ availability_topic:
required: false
type: string
device:
- description: "Information about the device this sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/siren.mqtt.markdown b/source/_integrations/siren.mqtt.markdown
index b330f5c4a9a..75f42cf8e5a 100644
--- a/source/_integrations/siren.mqtt.markdown
+++ b/source/_integrations/siren.mqtt.markdown
@@ -84,7 +84,7 @@ command_topic:
required: false
type: string
device:
- description: "Information about the device this siren is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this siren is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/snips.markdown b/source/_integrations/snips.markdown
index c2f8014ddd8..ce9365771c1 100644
--- a/source/_integrations/snips.markdown
+++ b/source/_integrations/snips.markdown
@@ -121,7 +121,7 @@ probability_threshold:
### Specifying the MQTT broker
-Messages between Snips and Home Assistant are passed via MQTT. We can either point Snips to the MQTT broker used by Home Assistant, as explained above, or tell Home Assistant which [MQTT broker](/docs/mqtt/) to use by adding the following entry to the `configuration.yaml` file:
+Messages between Snips and Home Assistant are passed via MQTT. We can either point Snips to the MQTT broker used by Home Assistant, as explained above, or tell Home Assistant which [MQTT broker](/integrations/mqtt) to use by adding the following entry to the `configuration.yaml` file:
```yaml
mqtt:
diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown
index 1ec680a194e..9df9c142283 100644
--- a/source/_integrations/switch.mqtt.markdown
+++ b/source/_integrations/switch.mqtt.markdown
@@ -71,7 +71,7 @@ command_topic:
required: false
type: string
device:
- description: "Information about the device this switch is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this switch is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/tag.mqtt.markdown b/source/_integrations/tag.mqtt.markdown
index fef5180e88f..d5eae095c2e 100644
--- a/source/_integrations/tag.mqtt.markdown
+++ b/source/_integrations/tag.mqtt.markdown
@@ -12,7 +12,7 @@ The `mqtt` tag scanner platform uses an MQTT message payload to generate tag sca
## Configuration
-MQTT scanners are only supported through [MQTT discovery](/docs/mqtt/discovery/), manual setup through `configuration.yaml` is not supported.
+MQTT scanners are only supported through [MQTT discovery](/integrations/mqtt/#mqtt-discovery), manual setup through `configuration.yaml` is not supported.
The discovery topic needs to be: `/tag/[/]/config`.
{% configuration %}
diff --git a/source/_integrations/text.mqtt.markdown b/source/_integrations/text.mqtt.markdown
index 5fd60fde2fc..e22d7125d84 100644
--- a/source/_integrations/text.mqtt.markdown
+++ b/source/_integrations/text.mqtt.markdown
@@ -67,7 +67,7 @@ command_topic:
required: true
type: string
device:
- description: "Information about the device this of text capability is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this of text capability is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/update.mqtt.markdown b/source/_integrations/update.mqtt.markdown
index 7c3b37bb56b..d886ba37f9f 100644
--- a/source/_integrations/update.mqtt.markdown
+++ b/source/_integrations/update.mqtt.markdown
@@ -64,7 +64,7 @@ command_topic:
required: false
type: string
device:
- description: "Information about the device this Update is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this Update is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_integrations/vacuum.mqtt.markdown b/source/_integrations/vacuum.mqtt.markdown
index c869e87a0c3..fa0eb95ef2f 100644
--- a/source/_integrations/vacuum.mqtt.markdown
+++ b/source/_integrations/vacuum.mqtt.markdown
@@ -367,7 +367,7 @@ command_topic:
required: false
type: string
device:
- description: "Information about the device this switch is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/docs/mqtt/discovery/) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
+ description: "Information about the device this switch is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
type: map
keys:
diff --git a/source/_redirects b/source/_redirects
index 662e9b27a75..a2e7650ce1b 100644
--- a/source/_redirects
+++ b/source/_redirects
@@ -233,7 +233,7 @@
/docs/mqtt/birth_will /integrations/mqtt/#birth-and-last-will-messages
/docs/mqtt/broker /integrations/mqtt/#broker-configuration
/docs/mqtt/certificate /integrations/mqtt/#advanced-broker-configuration
-/docs/mqtt/discovery /integrations/mqtt/#mqtt-discovery
+/integrations/mqtt/#mqtt-discovery /integrations/mqtt/#mqtt-discovery
/docs/mqtt/logging /integrations/mqtt/#logging
/docs/mqtt/service /integrations/mqtt/#publish--dump-services
/docs/mqtt/testing /integrations/mqtt/#testing-your-setup
diff --git a/source/docs/index.markdown b/source/docs/index.markdown
index e97d2950b09..08ebc44746c 100644
--- a/source/docs/index.markdown
+++ b/source/docs/index.markdown
@@ -19,7 +19,7 @@ The documentation covers beginner to advanced topics around the installation, se
Configuration
-
+