Merge branch 'master' into zeroconf_model_filter

2025-07-21 08:16:29 +00:00 · 2021-12-19 17:46:13 -06:00 · 2021-12-19 17:46:13 -06:00 · 9bd307cd8c
commit 9bd307cd8c
parent de15bdde90 9e156bab3b
34 changed files with 1974 additions and 3070 deletions
--- a/docs/add-ons.md
+++ b/docs/add-ons.md
@ -5,7 +5,7 @@ sidebar_label: Introduction
 Add-ons for Home Assistant allow the user to extend the functionality around Home Assistant. This can be running an application that Home Assistant can integrate with (like an MQTT broker) or to share the configuration via Samba for easy editing from other computers. Add-ons can be configured via the Supervisor panel in Home Assistant.
-Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.docker.com/). Developers can create [GitHub](https://github.com) repositories that contain multiple references to add-ons for easy sharing with the community.
+Under the hood, add-ons are container images published to a container registry like [GitHub container registry](https://github.com/features/packages) and [Docker Hub](https://hub.docker.com/). Developers can create [GitHub](https://github.com) repositories that contain multiple add-ons for easy sharing with the community.
 - [Tutorial: Making your first add-on](add-ons/tutorial.md)
 - [Configuration](add-ons/configuration.md)
@ -18,10 +18,11 @@ Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.
 Useful links:
- [Supervisor](https://github.com/home-assistant/supervisor)
+- [Example Add-on repository](https://github.com/home-assistant/addons-example)
- [Core Add-ons](https://github.com/home-assistant/hassio-addons)
+- [Home Assistant Supervisor](https://github.com/home-assistant/supervisor)
- [Docker base images](https://github.com/home-assistant/docker-base)
+- [Home Assistant Core Add-ons](https://github.com/home-assistant/addons)
- [Builder](https://github.com/home-assistant/hassio-builder)
+- [Home Assistant Docker base images](https://github.com/home-assistant/docker-base)
 - [Home Assistant Builder](https://github.com/home-assistant/builder)
 - [Home Assistant community Add-ons](https://github.com/hassio-addons)
 - [Home Assistant Operating System](https://github.com/home-assistant/operating-system)
- [Home Assistant Docker](https://github.com/home-assistant/docker)
+- [Home Assistant Docker images](https://github.com/home-assistant/docker)
--- a/docs/add-ons/configuration.md
+++ b/docs/add-ons/configuration.md
@ -7,11 +7,11 @@ Each add-on is stored in a folder. The file structure looks like this:
 ```text
 addon_name/
  translations/
-    en.(json/yaml/yml)
+    en.yaml
  apparmor.txt
-  build.(json/yaml/yml)
+  build.yaml
  CHANGELOG.md
-  config.(json/yaml/yml)
+  config.yaml
  DOCS.md
  Dockerfile
  icon.png
@ -20,6 +20,12 @@ addon_name/
  run.sh
 ```
 :::note
 Translation files, `config`  and `build` all support `.json`, `.yml` and `.yaml` as the file type.
 To keep it simple all examples are using `.yaml`
 :::
 ## Add-on script
 As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things.
@ -55,10 +61,10 @@ All add-ons are based on latest Alpine Linux image. Home Assistant will automati
 ARG BUILD_FROM
 FROM $BUILD_FROM
 ENV LANG C.UTF-8
 # Install requirements for add-on
-RUN apk add --no-cache example_alpine_package
+RUN \
  apk add --no-cache \
    example_alpine_package
 # Copy data for add-on
 COPY run.sh /
@ -70,10 +76,13 @@ CMD [ "/run.sh" ]
 If you don't use local build on device or our build script, make sure that the Dockerfile have also a set of labels include:
 ```dockerfile
-LABEL io.hass.version="VERSION" io.hass.type="addon" io.hass.arch="armhf|aarch64|i386|amd64"
+LABEL \
  io.hass.version="VERSION" \
  io.hass.type="addon" \
  io.hass.arch="armhf|aarch64|i386|amd64"
 ```
-It is possible to use own base image with `build.(json/yaml/yml)` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`.
+It is possible to use own base image with `build.yaml` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`.
 ### Build Args
@ -81,42 +90,23 @@ We support the following build arguments by default:
 | ARG | Description |
 |-----|-------------|
-| BUILD_FROM | Hold image for dynamic builds or buildings over our systems.
+| `BUILD_FROM` | Holds the image for dynamic builds or buildings over our systems.
-| BUILD_VERSION | Add-on version (read from `config.(json/yaml/yml)`).
+| `BUILD_VERSION` | Add-on version (read from `config.yaml`).
-| BUILD_ARCH | Hold current build arch inside.
+| `BUILD_ARCH` | Holds the current build arch inside.
-## Add-on config
+## Add-on configuration
-The configuration for an add-on is stored in `config.(json/yaml/yml)`.
+The configuration for an add-on is stored in `config.yaml`.
 ```json
 {
  "name": "xy",
  "version": "1.2",
  "slug": "folder",
  "description": "long description",
  "arch": ["amd64"],
  "url": "website with more information about add-on (e.g., a forum thread for support)",
  "startup": "application",
  "boot": "auto",
  "ports": {
    "123/tcp": 123
  },
  "map": ["config:rw", "ssl"],
  "image": "repo/{arch}-my-custom-addon"
 }
 ```
 ```yaml
-name: xy
+name: "Hello world"
-version: '1.2'
+version: "1.1.0"
 slug: folder
-description: long description
+description: >-
  "Long description"
 arch:
  - amd64
-url: website with more information about add-on (e.g., a forum thread for support)
+url: "website with more information about add-on (e.g., a forum thread for support)"
 startup: application
 boot: auto
 ports:
  123/tcp: 123
 map:
@ -125,103 +115,110 @@ map:
 image: repo/{arch}-my-custom-addon
 ```
-| Key | Type | Required | Description |
+### Required configuration options
 | Key | Type | Description |
 | --- | ---- | ----------- |
 | `name` | string | The name of the add-on.
 | `version` | string | Version of the add-on. If you are using a docker image with the `image` option, this needs to match the tag of the image that will be used.
 | `slug` | string | Slug of the add-on. This needs to be unique in the scope of the [repository](/docs/add-ons/repository) that the add-on is published in and URI friendly.
 | `description` | string | Description of the add-on.
 | `arch` | list | A list of supported architectures: `armhf`, `armv7`, `aarch64`, `amd64`, `i386`.
 ### Optional configuration options
 | Key | Type | Default | Description |
 | --- | ---- | -------- | ----------- |
-| name | string | yes | Name of the add-on.
+| `machine` | list | | Default it support any machine type. You can select that this add-on run only on specific machines. You can use `!` before a machine type to negate it. By default all machines are allowed.
-| version | string | yes | Version of the add-on. If using a docker image with the `image` option, this needs to match the tag of the image that is already published.
+| `url` | url | | Homepage of the add-on. Here you can explain the add-ons and options.
-| slug | string | yes | Slug of the add-on. This needs to be unique in the scope of the [repository](repository.md) that the add-on is published in and URI friendly.
+| `startup` | string | `application` | `initialize` will start add-on on setup of Home Assistant. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon.
-| description | string | yes | Description of the add-on.
+| `webui` | string | | An URL for the web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`.
-| arch | list | yes | List of supported arch: `armhf`, `armv7`, `aarch64`, `amd64`, `i386`.
+| `boot` | string | `auto` | `auto` start at boot is controlled by the system. `manual` for only manual starting.
-| machine | list | no | Default it support any machine type. You can select that this add-on run only on specific machines. You can use `!` before a machine type to negate it.
+| `ports` | dict | | Network ports to expose from the container. Format is `"container-port/type": host-port`. If the host port is `null` then the mapping is disabled.
-| url | url | no | Homepage of the add-on. Here you can explain the add-ons and options.
+| `ports_description` | dict | | Network ports description mapping. Format is `"container-port/type": "description of this port"`.
-| startup | string | no | Default `application`. `initialize` will start add-on on setup of Home Assistant. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon.
+| `host_network` | bool | `false` | If `true`, the add-on runs on host network.
-| webui | string | no | An URL for the web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`.
+| `host_ipc` | bool | `false` | Allow to share the IPC namespace with others.
-| boot | string | no | Default `auto`. `auto` start at boot is controlled by the system. `manual` for only manual starting.
+| `host_dbus` | bool | `false` | Map the host D-Bus service into the add-on.
-| ports | dict | no | Network ports to expose from the container. Format is `"container-port/type": host-port`. If the host port is `null` then the mapping is disabled.
+| `host_pid` | bool | `false` | Allow to run container on host PID namespace. Works only for not protected add-ons.
-| ports_description | dict | no | Network ports description mapping. Format is `"container-port/type": "description of this port"`.
+| `devices` | list | | Device list to map into the add-on. Format is: `<path_on_host>`. E.g., `/dev/ttyAMA0`
-| host_network | bool | no | If `true`, the add-on runs on host network.
+| `homeassistant` | string | | Pin a minimum required Home Assistant Core version for the add-on. Value is a version string like `0.91.2`.
-| host_ipc | bool | no | Default `false`. Allow to share the IPC namespace with others.
+| `hassio_role` | str | `default` |Role-based access to Supervisor API. Available: `default`, `homeassistant`, `backup`, `manager` or `admin`
-| host_dbus | bool | no | Default `false`. Map the host D-Bus service into the add-on.
+| `hassio_api` | bool | `false` | This add-on can access the Supervisor's REST API. Use `http://supervisor`.
-| host_pid | bool | no | Default `false`. Allow to run container on host PID namespace. Works only for not protected add-ons.
+| `homeassistant_api` | bool | `false` | This add-on can access to the Home Assistant REST API proxy. Use `http://supervisor/core/api`.
-| devices | list | no | Device list to map into the add-on. Format is: `<path_on_host>`. E.g., `/dev/ttyAMA0`
+| `docker_api` | bool | `false` | Allow read-only access to Docker API for add-on. Works only for not protected add-ons.
-| homeassistant | string | no | Pin a minimum required Home Assistant Core version for the add-on. Value is a version string like `0.91.2`.
+| `privileged` | list | | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `SYS_RESOURCE`, `SYS_PTRACE`, `SYS_MODULE` or `DAC_READ_SEARCH`
-| hassio_role | str | no | Default `default`. Role-based access to Supervisor API. Available: `default`, `homeassistant`, `backup`, `manager` or `admin`
+| `full_access` | bool | `false` | Give full access to hardware like the privileged mode in Docker. Works only for not protected add-ons. Consider using other add-on options instead of this, like `devices`. If you enable this option, don't add `devices`, `uart`, `usb` or `gpio` this is not needed.
-| hassio_api | bool | no | This add-on can access the Supervisor's REST API. Use `http://supervisor`.
+| `apparmor` | bool/string | `false` | Enable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile.
-| homeassistant_api | bool | no | This add-on can access to the Home Assistant REST API proxy. Use `http://supervisor/core/api`.
+| `map` | list | | List of maps for additional Home Assistant folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share` or `media`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name.
-| docker_api | bool | no | Allow read-only access to Docker API for add-on. Works only for not protected add-ons.
+| `environment` | dict | | A dictionary of environment variable to run add-on.
-| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `SYS_RESOURCE`, `SYS_PTRACE`, `SYS_MODULE` or `DAC_READ_SEARCH`
+| `audio` | bool | `false` | Mark this add-on to use internal audio system. We map a working PulseAudio setup into container. If your application does not support PulseAudio, you may need to install: Alpine Linux `alsa-plugins-pulse` or Debian/Ubuntu `libasound2-plugins`.
-| full_access | bool | no | Give full access to hardware like the privileged mode in Docker. Works only for not protected add-ons. Consider using other add-on options instead of this, like `devices`. If you enable this option, don't add `devices`, `uart`, `usb` or `gpio` this is not needed.
+| `video` | bool | `false` | Mark this add-on to use the internal video system. All available devices will be mapped into the add-on.
-| apparmor | bool/string | no | Enable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile.
+| `gpio` | bool | `false` | If this is set to `true`, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some libraries also need  `/dev/mem` and `SYS_RAWIO` for read/write access to this device. On systems with AppArmor enabled, you need to disable AppArmor or provide you own profile for the add-on, which is better for security.
-| map | list | no | List of maps for additional Home Assistant folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share` or `media`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name.
+| `usb` | bool | `false` | If this is set to `true`, it would map the raw USB access `/dev/bus/usb` into add-on with plug&play support.
-| environment | dict | no | A dictionary of environment variable to run add-on.
+| `uart` | bool | `false` | Default `false`. Auto mapping all UART/serial devices from the host into the add-on.
-| audio | bool | no | Mark this add-on to use internal audio system. We map a working PulseAudio setup into container. If your application does not support PulseAudio, you may need to install: Alpine Linux `alsa-plugins-pulse` or Debian/Ubuntu `libasound2-plugins`.
+| `udev` | bool | `false` | Default `false`. Set this `true`, gets the host udev database read-only mounted into the add-on.
-| video | bool | no | Mark this add-on to use the internal video system. All available devices will be mapped into the add-on.
+| `devicetree` | bool | `false` | If this is set to True, `/device-tree` will map into add-on.
-| gpio | bool | no | If this is set to `true`, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some libraries also need  `/dev/mem` and `SYS_RAWIO` for read/write access to this device. On systems with AppArmor enabled, you need to disable AppArmor or provide you own profile for the add-on, which is better for security.
+| `kernel_modules` | bool | `false` | Map host kernel modules and config into add-on (readonly) and give you SYS_MODULE permission.
-| usb | bool | no | If this is set to `true`, it would map the raw USB access `/dev/bus/usb` into add-on with plug&play support.
+| `stdin` | bool | `false` | If enabled, you can use the STDIN with Home Assistant API.
-| uart | bool | no | Default `false`. Auto mapping all UART/serial devices from the host into the add-on.
+| `legacy` | bool | `false` | If the Docker image has no `hass.io` labels, you can enable the legacy mode to use the config data.
-| udev | bool | no | Default `false`. Set this `true`, gets the host udev database read-only mounted into the add-on.
+| `options` | dict | | Default options value of the add-on.
-| devicetree | bool | no | Boolean. If this is set to True, `/device-tree` will map into add-on.
+| `schema` | dict | | Schema for options value of the add-on. It can be `false` to disable schema validation and options.
-| kernel_modules | bool | no | Map host kernel modules and config into add-on (readonly) and give you SYS_MODULE permission.
+| `image` | string | | For use with Docker Hub and other container registries. This should be set to the name of the image only (E.g, `ghcr.io/home-assistant/{arch}-addon-example`). If you use this option, set the active docker tag using the `version` option.
-| stdin | bool | no | Boolean. If enabled, you can use the STDIN with Home Assistant API.
+| `timeout` | integer | | Default 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed.
-| legacy | bool | no | Boolean. If the Docker image has no `hass.io` labels, you can enable the legacy mode to use the config data.
+| `tmpfs` | bool | `false` | If this is set to `true`, the containers `/tmp` is using tmpfs, a memory file system.
-| options | dict | no | Default options value of the add-on.
+| `discovery` | list | | A list of services that this add-on provides for Home Assistant. Currently supported: `mqtt`
-| schema | dict | no | Schema for options value of the add-on. It can be `false` to disable schema validation and options.
+| `services` | list | | A list of services that will be provided or consumed with this add-on. Format is `service`:`function` and functions are: `provide` (this add-on can provide this service), `want` (this add-on can use this service) or `need` (this add-on need this service to work correctly).
-| image | string | no | For use with Docker Hub and other container registries. This should be set to the name of the image only (E.g, `ghcr.io/home-assistant/{arch}-addon-example`). If you use this option, set the active docker tag using the `version` option.
+| `auth_api` | bool | `false` | Allow access to Home Assistant user backend.
-| timeout | integer | no | Default 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed.
+| `ingress` | bool | `false` | Enable the ingress feature for the add-on.
-| tmpfs | bool | no | If this is set to `true`, the containers `/tmp` is using tmpfs, a memory file system.
+| `ingress_port` | integer | `8099` | For add-ons that run on the host network, you can use `0` and read the port later via API.
-| discovery | list | no | A list of services that this add-on provides for Home Assistant. Currently supported: `mqtt`
+| `ingress_entry` | string | `/` | Modify the URL entry point.
-| services | list | no | A list of services that will be provided or consumed with this add-on. Format is `service`:`function` and functions are: `provide` (this add-on can provide this service), `want` (this add-on can use this service) or `need` (this add-on need this service to work correctly).
+| `ingress_stream` | bool | `false` | When enabled requests to the add-on are streamed
-| auth_api | bool | no | Allow access to Home Assistant user backend.
+| `panel_icon` | string | `mdi:puzzle` | [MDI icon](https://materialdesignicons.com/) for the menu panel integration.
-| ingress | bool | no | Enable the ingress feature for the add-on.
+| `panel_title` | string | | Defaults to the add-on name, but can be modified with this option.
-| ingress_port | integer | no | Default `8099`. For add-ons that run on the host network, you can use `0` and read the port later via API.
+| `panel_admin` | bool | `true` | Make menu entry only available with users in the admin group.
-| ingress_entry | string | no | Modify the URL entry point from `/`.
+| `backup` | string | `hot` | `hot` or `cold`. If `cold`, the supervisor turns the add-on off before taking a backup (the `pre/post` options are ignored when `cold` is used).
-| ingress_stream | bool | no | Default `false`, when enabled POST requests to the add-on are streamed
+| `backup_pre` | string | | Command to execute in the context of the add-on before the backup is taken.
-| panel_icon | string | no | Default: `mdi:puzzle`. MDI icon for the menu panel integration.
+| `backup_post` | string | | Command to execute in the context of the add-on after the backup was taken.
-| panel_title | string | no | Default is the add-on name, but can be modified with this option.
+| `backup_exclude` | list | | List of file/path (with glob support) that are excluded from backups.
-| panel_admin | bool | no | Default `true`. Make menu entry only available with admin privileged.
+| `advanced` | bool | `false` | Set this to `true` to require the user to have enabled "Advanced" mode for it to show.
-| backup | string | no | `hot` (default) or `cold`. If `cold`, the supervisor turns the add-on off before taking a backup (the `pre/post` options are ignored when `cold` is used).
+| `stage` | string | `stable` | Flag add-on with follow attribute: `stable`, `experimental` or `deprecated`
-| backup_pre | string | no | Command to execute in the context of the add-on before the backup is taken.
+| `init` | bool | `true` | Set this to `false` to disable the Docker default system init. Use this if the image has its own init system (Like [s6-overlay](https://github.com/just-containers/s6-overlay)).
-| backup_post | string | no | Command to execute in the context of the add-on after the backup was taken.
+| `watchdog` | string | | An URL for monitor an application this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`. For simple TCP port monitoring you can use `tcp://[HOST]:[PORT:80]`. It work for add-ons on host or internal network.
-| backup_exclude | list | no | List of file/path (with glob support) that are excluded from backups.
+| `realtime` | bool | `false` | Give add-on access to host schedule including `SYS_NICE` for change execution time/priority.
-| advanced | bool | no | Default `false`. Make addon visible in simple mode.
+| `journald` | bool | `false` | If set to `true`, the host's system journal will be mapped read-only into the add-on. Most of the time the journal will be in `/var/log/journal` however on some hosts you will find it in `/run/log/journal`. Add-ons relying on this capability should check if the directory `/var/log/journal` is populated and fallback on `/run/log/journal` if not.
 | stage | string | no | Default `stable`. Flag add-on with follow attribute: `stable`, `experimental` or `deprecated`
 | init | bool | no | Default `true`. Disable the Docker default system init.  Use this if the image has its own init system.
 | watchdog | string | no | An URL for monitor an application this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`. For simple TCP port monitoring you can use `tcp://[HOST]:[PORT:80]`. It work for add-ons on host or internal network.
 | realtime | bool | no | Give add-on access to host schedule including SYS_NICE for change execution time/priority.
 | journald | bool | no | Default `false`. If set to `true`, the host's system journal will be mapped read-only into the add-on. Most of the time the journal will be in `/var/log/journal` however on some hosts you will find it in `/run/log/journal`. Add-ons relying on this capability should check if the directory `/var/log/journal` is populated and fallback on `/run/log/journal` if not.
 ### Options / Schema
 The `options` dictionary contains all available options and their default value. Set the default value to `null` if the value is required to be given by the user before the add-on can start, and it show it inside default values. Only nested arrays and dictionaries are supported with a deep of two size. If you want make an option optional, put `?` to the end of data type, otherwise it will be a required value.
-```json
+```yaml
-{
+message: "custom things"
-  "message": "custom things",
+logins:
-  "logins": [
+  - username: beer
-    { "username": "beer", "password": "123456" },
+    password: "123456"
-    { "username": "cheep", "password": "654321" }
+  - username: cheep
-  ],
+    password: "654321"
-  "random": ["haha", "hihi", "huhu", "hghg"],
+random:
-  "link": "http://example.com/",
+  - haha
-  "size": 15,
+  - hihi
-  "count": 1.2
+link: "http://example.com/"
-}
+size: 15
 count: 1.2
 ```
 The `schema` looks like `options` but describes how we should validate the user input. For example:
-```json
+```yaml
-{
+message: str
-  "message": "str",
+logins:
-  "logins": [
+  - username: str
-    { "username": "str", "password": "str" }
+    password: str
-  ],
+random:
-  "random": ["match(^\\w*$)"],
+  - "match(^\\w*$)"
-  "link": "url",
+link: url
-  "size": "int(5,20)",
+size: "int(5, 20)"
-  "count": "float",
+count: float
-  "not_need": "str?"
+not_need: "str?"
 }
 ```
 We support:
@ -240,21 +237,9 @@ We support:
 ## Add-on extended build
-Additional build options for an add-on is stored in `build.(json/yaml/yml)`. This file will be read from our build systems.
+Additional build options for an add-on is stored in `build.yaml`. This file will be read from our build systems.
 You need this only, if you not use the default images or need additional things.
 ```json
 {
  "build_from": {
    "armhf": "mycustom/base-image:latest"
  },
  "squash": false,
  "args": {
    "my_build_arg": "xy"
  }
 }
 ```
 ```yaml
 build_from:
  armhf: mycustom/base-image:latest
@ -269,6 +254,9 @@ args:
 | squash | no | Default `False`. Be careful with this option, as you can not use the image for caching stuff after that!
 | args | no | Allow to set additional Docker build arguments as a dictionary.
 | labels | no | Allow to set additional Docker labels as a dictionary.
 | codenotary | no | Allows to enable container signature with codenotary CAS.
 | codenotary.signer | no | Owner signer E-Mail address for this image.
 | codenotary.base_image | no | Verify the base container image. If you use our official images, use `notary@home-assistant.io`
 We provide a set of [base images][docker-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific image tag, feel free to pin this requirements for you build with `build_from` option.
@ -278,7 +266,7 @@ We provide a set of [base images][docker-base] which should cover a lot of needs
 Add-ons can provide translation files for configuration options that are used in the UI.
-Example path to translation file: `addon/translations/{language_code}.(json/yaml/yml)`
+Example path to translation file: `addon/translations/{language_code}.yaml`
 For `{language_code}` use a valid language code, like `en`, for a [full list have a look here](https://github.com/home-assistant/frontend/blob/dev/src/translations/translationMetadata.json), `en.yaml` would be a valid filename.
--- a/docs/add-ons/presentation.md
+++ b/docs/add-ons/presentation.md
@ -51,9 +51,10 @@ By default, AppArmor gives you a certain level of security by restricting some g
 As for Home Assistant's implementation, you can activate your own custom AppArmor profile by putting an `apparmor.txt` file into your add-on folder. Adding your own `apparmor.txt` will load that file as the primary AppArmor profile instead of the default implementation. On top of knowing your add-on will run in a constrained and effective manner, writing your own custom `apparmor.txt` file will earn your add-on a security point after your add-on is installed, thus improving your user's confidence and perception of your add-on.
-An `apparmor.txt` goes in the same folder as your `config.json` file. Below is an example `apparmor.txt`. Replace `ADDON_SLUG` with the slug defined in your add-on configuration.
+An `apparmor.txt` goes in the same folder as your `config.yaml` file. Below is an example `apparmor.txt`. Replace `ADDON_SLUG` with the slug defined in your add-on configuration.
 apparmor.txt
 ```txt
 #include <tunables/global>
@ -79,7 +80,7 @@ profile ADDON_SLUG flags=(attach_disconnected,mediate_deleted) {
  /usr/lib/bashio/** ix,
  /tmp/** rw,
-  # Access to Options.json and other files within your addon
+  # Access to options.json and other files within your addon
  /data/** rw,
  # Start new profile for service
@ -99,8 +100,8 @@ profile ADDON_SLUG flags=(attach_disconnected,mediate_deleted) {
 Ingress allows users to access the add-on web interface via the Home Assistant UI. Authentication is handled by Home Assistant, so neither the user nor the add-on developer will need to care about the security or port forwarding. Users love this feature! It connects your user directly to the add-on, can provide a seamless UX within Home Assistant and grants your add-on 2 points of security.
 Here are the requirements of Ingress:
- Ingress must be enabled. Set `ingress: true` in [`config.json`](/docs/add-ons/configuration#add-on-config).
+- Ingress must be enabled. Set `ingress: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options).
- Your server may run on port 8099. If it does not run on 8099, you must set `ingress_port: PORT_NUMBER` in [`config.json`](/docs/add-ons/configuration/#add-on-config) to match your configuration.
+- Your server may run on port 8099. If it does not run on 8099, you must set `ingress_port: PORT_NUMBER` in [`config.yaml`](/docs/add-ons/configuration/#add-on-config) to match your configuration.
 - Only connections from `172.30.32.2` must be allowed. You should deny access to all other IP addresses within your add-on server. 
 - Users are previously authenticated via Home Assistant. Authentication is not required. 
@ -117,12 +118,13 @@ Ingress API gateway supports the following:
 ## Basic Ingress Example with Nginx
-The following is a basic ingress implementation with an Nginx server. This contains an example`Dockerfile`, `config.json`, and `ingress.conf` configuration.
+The following is a basic ingress implementation with an Nginx server. This contains an example`Dockerfile`, `config.yaml`, and `ingress.conf` configuration.
-The `ingress.conf` is configured to accept only connections from IP address `172.30.32.2` as we are only expecting connections from this IP address for Ingress purposes. Any other IP address will be rejected. The ingress port 8099 is utilized to reduce configuration work. If you wish to configure a different ingress port you may, but the `config.json` option `ingress_port` must be defined to match.
+The `ingress.conf` is configured to accept only connections from IP address `172.30.32.2` as we are only expecting connections from this IP address for Ingress purposes. Any other IP address will be rejected. The ingress port 8099 is utilized to reduce configuration work. If you wish to configure a different ingress port you may, but the `config.yaml` option `ingress_port` must be defined to match.
 ingress.conf
-```nginx 
+
 ```nginx
 server {
    listen 8099;
    allow  172.30.32.2;
@ -133,37 +135,45 @@ server {
 Our example `Dockerfile` is configured to support only our Nginx server and does not support a `run.sh` like most add-ons. You may replace the `CMD` with your own command to allow more configuration options while launching your add-on. This Dockerfile will `RUN` to install our Nginx dependencies, `COPY` our example `ingress.conf` from above to the add-on container, then `CMD` start Nginx.
 Dockerfile
-```Dockerfile
+
 ```dockerfile
 ARG BUILD_FROM
 FROM $BUILD_FROM
 ENV LANG C.UTF-8
 #Add nginx and create the run folder for nginx.
-RUN apk --no-cache  add nginx;mkdir -p /run/nginx;
+RUN \
  apk --no-cache add \
    nginx \
  \
  && mkdir -p /run/nginx
 #Copy our conf into the nginx http.d folder.
 COPY ingress.conf /etc/nginx/http.d/
 #Launch nginx with debug options.
 CMD [ "nginx","-g","daemon off;error_log /dev/stdout debug;" ]
 ```
-In order to enable Ingress, our `config.json` file _must_ include `ingress: true` and _may_ specify the `ingress_port`, along with other required information.
+In order to enable Ingress, our `config.yaml` file _must_ include `ingress: true` and _may_ specify the `ingress_port`, along with other required information.
-config.json
+config.yaml
-```json
+
-{
+```yaml
-  "name": "Ingress Example",
+name: "Ingress Example"
-  "version": "0.00.0.0.000.0.000",
+version: "1.0.0"
-  "slug": "nginx-ingress-example",
+slug: "nginx-ingress-example"
-  "description": "ingress testing",
+description: "Ingress testing"
-  "arch": ["armhf", "armv7", "aarch64", "amd64", "i386"],
+arch:
-  "ingress": true,
+  - amd64
-  "ingress_port": 8099
+  - armhf
-}
+  - armv7
  - i386
 ingress: true
 ```
 After the add-on is started, you should be able to view your Ingress server by clicking "OPEN WEB UI" within the add-on info screen.
-# Security
+## Security
 Add-on security should be a matter of pride. You should strive for the highest level of security you can possibly attain. If your add-on has a lower security rating, then users will be less likely to trust it.
@ -171,14 +181,14 @@ Each add-on starts with a base rating of 5, on a scale of 1 to 6. Depending on d
 | Action | Change | Notes |
 |---|---|---|
-| Use `ingress: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | +2 | overrides `auth_api` rating |
+| Use `ingress: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | +2 | overrides `auth_api` rating |
-| Use `auth_api: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | +1 | overridden by `ingress` |
+| Use `auth_api: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | +1 | overridden by `ingress` |
 | Use custom [`apparmor.txt`](/docs/add-ons/presentation#apparmor)| +1| Rating applied after installation |
-| Set `apparmor: false` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -1 | |
+| Set `apparmor: false` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -1 | |
-| Use `privileged: NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_PTRACE`, `SYS_MODULE`, or `DAC_READ_SEARCH`, or `kernel_modules: ` used in [`config.json`](/docs/add-ons/configuration#add-on-config)| -1 | Rating applied only once if multiple are used. |
+| Use `privileged: NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_PTRACE`, `SYS_MODULE`, or `DAC_READ_SEARCH`, or `kernel_modules: ` used in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options)| -1 | Rating applied only once if multiple are used. |
-| Use `hassio_role: manager` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -1 | |
+| Use `hassio_role: manager` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -1 | |
-| Use `host_network: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -1 | |
+| Use `host_network: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -1 | |
-| Use `hassio_role: admin` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -2 | |
+| Use `hassio_role: admin` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -2 | |
-| Use `host_pid: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -2 | |
+| Use `host_pid: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -2 | |
-| Use `full_access: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | Security set to 1 | Overrides all other adjustments |
+| Use `full_access: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | Security set to 1 | Overrides all other adjustments |
-| Use `docker_api: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | Security set to 1 | Overrides all other adjustments |
+| Use `docker_api: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | Security set to 1 | Overrides all other adjustments |
--- a/docs/add-ons/publishing.md
+++ b/docs/add-ons/publishing.md
@ -2,55 +2,63 @@
 title: "Publishing your add-on"
 ---
-There are two different ways of publishing add-ons. One is to publish pre-built containers to Docker Hub and the other option is to have users build the containers locally on their Home Assistant instance.
+There are two different ways of publishing add-ons. One is to publish pre-built containers to a container registry and the other option is to have users build the containers locally on their Home Assistant instance.
 #### Pre-built containers
-With pre-built containers, the developer is responsible for building the images for each architecture on their machine and push the results out to Docker Hub. This has a lot of advantages for the user. As a user it will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and almost no chance of failure. This is the preferred method.
+With pre-built containers, the developer is responsible for building the images for each architecture on their machine and push the results out to a container registry. This has a lot of advantages for the user. As a user it will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and almost no chance of failure. This is the preferred method.
 We have automated the process of building and publishing add-ons. See below for the instructions.
 #### Locally build containers
-Starting with Supervisor 26, it is possible to distribute add-ons that will be built on the users machine. The advantage is that as a developer it is easy to test an idea and see if people are interested in your add-ons. This method includes installing and potentially compiling code. This means that installing such an add-on is slow and adds more wear and tear to users SD card/hard drive than the above mentioned pre-built solution. It also has a higher chance of failure if one of the dependencies of the container has changed or is no longer available.
+With the Supervisor, it is possible to distribute add-ons that will be built on the users machine. The advantage is that as a developer it is easy to test an idea and see if people are interested in your add-ons. This method includes installing and potentially compiling code. This means that installing such an add-on is slow and adds more wear and tear to users SD card/hard drive than the above mentioned pre-built solution. It also has a higher chance of failure if one of the dependencies of the container has changed or is no longer available.
-Use this option when you are playing with add-ons and seeing if someone is interested in your work. Once you're an established repository, please migrate to pushing builds to Docker Hub as it greatly improves the user experience. In the future we will mark locally built add-ons in the add-on store to warn users.
+Use this option when you are playing with add-ons and seeing if someone is interested in your work. Once you're an established repository, please migrate to pushing builds to a container registry as it greatly improves the user experience. In the future we will mark locally built add-ons in the add-on store to warn users.
-## Build scripts to publish add-ons to Docker Hub
+## Build scripts to publish add-ons to a container registry
-All add-ons are simple docker containers. Inside your add-on `config.json` you specify the Docker image that will be installed for your add-on:
+All add-ons are containers. Inside your add-on `config.yaml` you specify the container image that will be installed for your add-on:
-```json
+```yaml
-{
+...
-  ...
+image: "myhub/image-{arch}-addon-name"
-  "image": "myhub/image-{arch}-addon-name",
+...
  ...
 }
 ```
-You can use `{arch}` inside the image name to support multiple architectures with one (1) configuration file. It will be replaced with the architecture of the user when we load the image. If you use `Buildargs` you can use the `build.json` to overwrite our default args.
+You can use `{arch}` inside the image name to support multiple architectures with one (1) configuration file. It will be replaced with the architecture of the user when we load the image. If you use `Buildargs` you can use the `build.yaml` to overwrite our default args.
-Home Assistant assumes that the default branch of your add-on repository matches the latest tag on Docker Hub. When you're building a new version, it's suggested that you use another branch, ie `build` or do it with a PR on GitHub. After you push the add-on to [Docker Hub](https://hub.docker.com/), you can merge this branch to master.
+Home Assistant assumes that the default branch of your add-on repository matches the latest tag on the container registry. When you're building a new version, it's suggested that you use another branch, ie `build` or do it with a PR on GitHub. After you push the add-on to a container registry, you can merge this branch to master.
 ## Custom Add-ons
-You need a Docker Hub account to make your own add-ons. You can build your Docker images with the Docker `build` command or use our script that make it simple. Pull our [Builder Docker engine][builder] and run one of the following commands.
+You need a Docker Hub account to make your own add-ons. You can build your container images with the Docker `build` command or use our [builder] that make it simple. Pull our [Builder Docker engine][builder] and run one of the following commands.
 For a git repository:
 ```shell
-docker run --rm --privileged -v \
+docker run \
-  ~/.docker:/root/.docker homeassistant/amd64-builder \
+  --rm \
-  --all -t addon-folder -r https://github.com/xy/addons \
+  --privileged \
  -v ~/.docker:/root/.docker \
  homeassistant/amd64-builder \
  --all \
  -t addon-folder \
  -r https://github.com/xy/addons \
  -b branchname
 ```
 For a local repository:
 ```shell
-docker run --rm --privileged -v \
+docker run \
-  ~/.docker:/root/.docker -v /my_addon:/data homeassistant/amd64-builder \
+  --rm \
-  --all -t /data
+  --privileged \
  -v ~/.docker:/root/.docker \
  -v /my_addon:/data \
  homeassistant/amd64-builder \
  --all \
  -t /data
 ```
 :::tip
--- a/docs/add-ons/repository.md
+++ b/docs/add-ons/repository.md
@ -10,17 +10,13 @@ Check the [Example add-on repository](https://github.com/home-assistant/addons-e
 A user can add a repository by going to the Supervisor panel in Home Assistant, clicking on the store icon in the top right, copy/paste the URL of your repository into the repository textarea and click on **Save**.
 :::tip
 You can generate a [my.home-assistant.io](https://my.home-assistant.io/create-link/) for your users to do this with the click of a button in your readme file.
 :::
 ## Repository configuration
-Each repository is required to contain `repository.(json/yaml/yml)` at the root in the git repository.
+Each repository is required to contain `repository.yaml` at the root in the git repository.
 ```json
 {
  "name": "Name of repository",
  "url": "http://www.example/addons",
  "maintainer": "HomeAssistant Team <info@home-assistant.io>"
 }
 ```
 ```yaml
 name: Name of repository
@ -30,6 +26,6 @@ maintainer: HomeAssistant Team <info@home-assistant.io>
 | Key | Required | Description |
 | --- | -------- | ----------- |
-| name | yes | Name of the repository
+| `name` | yes | Name of the repository
-| url | no | Homepage of the repository. Here you can explain the various add-ons.
+| `url` | no | Homepage of the repository. Here you can explain the various add-ons.
-| maintainer | no | Contact info of the maintainer.
+| `maintainer` | no | Contact info of the maintainer.
--- a/docs/add-ons/security.md
+++ b/docs/add-ons/security.md
@ -6,17 +6,17 @@ Home Assistant rates every add-on based on the wanted rights. An add-on with a r
 ## API Role
-For access to Supervisor API you need define a role or you run in default mode. This is only required for Supervisor API not Home Assistant proxy. Any of the roles already have access to the default API calls, and do not require any additional settings.
+For access to Supervisor API you need to define a role or you run in default mode. This is only required for Supervisor API not Home Assistant proxy. Any of the roles already have access to the default API calls, and do not require any additional settings.
 ### Available Roles
 | Role | Description |
 |------|-------------|
-| default | Have access to all `info` calls |
+| `default` | Have access to all `info` calls |
-| homeassistant | Can access all Home Assistant API endpoints |
+| `homeassistant` | Can access all Home Assistant API endpoints |
-| backup | Can access all backup API endpoints |
+| `backup` | Can access all backup API endpoints |
-| manager | Is for Add-ons that run CLIs and need extended rights |
+| `manager` | Is for Add-ons that run CLIs and need extended rights |
-| admin | Have access to every API call. That is the only one they can disable/enable the Add-on protection mode |
+| `admin` | Have access to every API call. That is the only one they can disable/enable the Add-on protection mode |
 ## Protection
--- a/docs/add-ons/testing.md
+++ b/docs/add-ons/testing.md
@ -2,45 +2,42 @@
 title: "Local add-on testing"
 ---
-The fastest and recommended way to develop add-ons is using a local Visual Studio Code dev environment. The [Official Add-ons][hassio-addons] repository includes a dev container setup for VS Code which will run Supervisor and Home Assistant, with all of the add-ons mapped as Local Add-ons inside, making it simple for add-on developers on Windows, Mac and Linux desktop OS-es. 
+The fastest and recommended way to develop add-ons is using a local Visual Studio Code devcontainer. We maintain a [devcontainer for this purpose](https://github.com/home-assistant/devcontainer) which is used in all our add-ons repositories. This devcontainer setup for VS Code which will run Supervisor and Home Assistant, with all of the add-ons mapped as Local Add-ons inside, making it simple for add-on developers on Windows, Mac and Linux desktop OS-es.
- Follow the instructions to download and install the [Remote Containers][remote-containers] VS Code extension.
+- Follow the instructions to download and install the [Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) VS Code extension.
- Copy the `.devcontainer` and `.vscode` folder from [Official Add-ons][hassio-addons] repository into the root of your add-ons folders.
+- Copy the [`devcontainer.json` file](https://github.com/home-assistant/devcontainer/blob/main/addons/devcontainer.json) to `.devcontainer/devcontainer.json` in your repository.
- Open the root folder inside VS Code, and when prompted re-open the window inside the container (or, from the Command Palette, select 'Rebuild and Reopen in Container'). 
+- Copy the [`tasks.json` file](https://github.com/home-assistant/devcontainer/blob/main/addons/tasks.json) to `.vscode/tasks.json` in your repository.
- When VS Code has opened your folder in the container (which can take some time for the first run) you'll need to run the task (Terminal -> Run Task) 'Start Home Assistant', which will bootstrap Supervisor and Home Assistant. 
+- Open the root folder inside VS Code, and when prompted re-open the window inside the container (or, from the Command Palette, select 'Rebuild and Reopen in Container').
 - When VS Code has opened your folder in the container (which can take some time for the first run) you'll need to run the task (Terminal -> Run Task) 'Start Home Assistant', which will bootstrap Supervisor and Home Assistant.
 - You'll then be able to access the normal onboarding process via the Home Assistant instance at `http://localhost:7123/`.
 - The add-on(s) found in your root folder will automatically be found in the Local Add-ons repository.
 [hassio-addons]: https://github.com/home-assistant/hassio-addons
 [remote-containers]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
 :::info
 The bootstrap script `start_supervisor.sh` currently does not support Docker on Windows using the WSL 2 based engine. The message "_Timeout while waiting for docker to come up_" will appear in the terminal.
 If you are using Docker Desktop and have Hyper-V support, you can switch back to legacy Hyper-V backend in Settings > General.
 :::
 ## Remote development
-If you require access to physical hardware or other resources that cannot be locally emulated (for example, serial ports), the next best option to develop add-ons is by adding them to the local add-on repository on a real device running Home Assistant. To access the local add-on repository on a remote device, install either the [Samba add-on] or [SSH add-on] and copy the add-on files to a subdirectory of `/addons`.
+If you require access to physical hardware or other resources that cannot be locally emulated (for example, serial ports), the next best option to develop add-ons is by adding them to the local add-on repository on a real device running Home Assistant. To access the local add-on repository on a remote device, install either the [Samba](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_samba) or the [SSH](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_ssh) add-ons and copy the add-on files to a subdirectory of `/addons`.
-Right now add-ons will work with images that are stored on Docker Hub (using `image` from add-on config). To ensure that the add-on is built locally and not fetched from an upstream repository, ensure that the `image` key is *not* present in your `config.json`.
+Right now add-ons will work with images that are stored on Docker Hub (using `image` from add-on config). To ensure that the add-on is built locally and not fetched from an upstream repository, ensure that the `image` key is commented out in your `config.yaml` file (You can do that by adding a `#` in front of it, like `#image: xxx`).
 [Samba add-on]: https://www.home-assistant.io/addons/samba/
 [SSH add-on]: https://www.home-assistant.io/addons/ssh/
 ## Local build
 If you don't want to use the devcontainer environment, you can still build add-ons locally with Docker. The recommended method is to use the [official build tool][hassio-builder] to create the Docker images.
 Assuming that your addon is in the folder `/path/to/addon` and your Docker socket is at `/var/run/docker.sock`, you can build the addon for all supported architectures by running the following:
-```
+
-docker run --rm -ti --name hassio-builder --privileged \
+```shell
 docker run \
  --rm \
  -it \
  --name builder \
  --privileged \
  -v /path/to/addon:/data \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
-  homeassistant/amd64-builder -t /data --all --test \
+  homeassistant/amd64-builder \
-  -i my-test-addon-{arch} -d local
+  -t /data \
  --all \
  --test \
  -i my-test-addon-{arch} \
  -d local
 ```
 If you don't want to use the official build tool, you can still build with standalone Docker. If you use `FROM $BUILD_FROM` you'll need to set a base image with build args. Normally you can use follow base images:
@ -50,10 +47,13 @@ If you don't want to use the official build tool, you can still build with stand
 - amd64: `homeassistant/amd64-base:latest`
 - i386: `homeassistant/i386-base:latest`
-Use `docker` from the directory containing the add-on files to build the test addon: 
+Use `docker` from the directory containing the add-on files to build the test addon:
-```
+
-docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" \
+```shell
-  -t local/my-test-addon .
+docker build \
  --build-arg BUILD_FROM="homeassistant/amd64-base:latest" \
  -t local/my-test-addon \
  .
 ```
 [hassio-builder]: https://github.com/home-assistant/hassio-builder
@ -62,9 +62,13 @@ docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" \
 If you don't want to use the devcontainer environment, you can still run add-ons locally with Docker.
-Create a new folder for data and add a test _options.json_ file. After that you can run your add-on with: 
+Create a new folder for data and add a test _options.json_ file. After that you can run your add-on with:
-```
+
-docker run --rm -v /tmp/my_test_data:/data -p PORT_STUFF_IF_NEEDED \
+```shell
 docker run \
  --rm \
  -v /tmp/my_test_data:/data \
  -p PORT_STUFF_IF_NEEDED \
  local/my-test-addon
 ```
--- a/docs/add-ons/tutorial.md
+++ b/docs/add-ons/tutorial.md
@ -2,37 +2,36 @@
 title: "Tutorial: Making your first add-on"
 ---
-So you've got Home Assistant going and you've been enjoying the built-in add-ons but you're missing this one application. Time to make your own add-on! In Supervisor 24 we introduced the option to have local add-ons be built on your device. This is great for developing new add-ons locally.
+So you've got Home Assistant going and you've been enjoying the built-in add-ons but you're missing this one application. Time to make your own add-on!
-To get started with developing add-ons, we first need access to where Home Assistant looks for local add-ons. For this you can use the Samba add-on or the SSH add-on.
+To get started with developing add-ons, we first need access to where Home Assistant looks for local add-ons. For this you can use the [Samba](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_samba) or the [SSH](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_ssh) add-ons.
 For Samba, once you have enabled and started it, your Home Assistant instance will show up in your local network tab and share a folder called "addons". This is the folder to store your custom add-ons.
-If you are on macOS and the folder is not showing up automatically, go to Finder and press CMD+K then enter 'smb://homeassistant.local'
+:::tip
 If you are on macOS and the folder is not showing up automatically, go to Finder and press CMD+K then enter `smb://homeassistant.local`
 :::
-![Screenshot of Windows Explorer showing a folder on the Home Assistant server](/img/en/hass.io/tutorial/samba.png)
+For SSH, you will have to install it. Before you can start it, you will have to have a private/public key pair and store your public key in the add-on config ([see docs for more info](https://github.com/home-assistant/addons/blob/master/ssh/DOCS.md#configuration)). Once started, you can SSH to Home Assistant and store your custom add-ons in the `/addons` directory.
 For SSH, you will have to install it. Before you can start it, you will have to have a private/public key pair and store your public key in the add-on config ([see docs for more info][ssh]). Once started, you can SSH to Home Assistant and store your custom add-ons in "/addons".
 ![Screenshot of Putty connected to Home Assistant](/img/en/hass.io/tutorial/ssh.png)
 Once you have located your add-on directory, it's time to get started!
 [ssh]: https://www.home-assistant.io/addons/ssh/
 ## Step 1: The basics
 - Create a new directory called `hello_world`
- Inside that directory create three files.
+- Inside that directory create three files:
  - `Dockerfile`
  - `config.yaml`
  - `run.sh`
-`Dockerfile`:
+### The `Dockerfile` file
 This is the image that will be used to build your add-on.
 ```dockerfile
 ARG BUILD_FROM
 FROM $BUILD_FROM
 ENV LANG C.UTF-8
 # Copy data for add-on
 COPY run.sh /
 RUN chmod a+x /run.sh
@ -40,51 +39,59 @@ RUN chmod a+x /run.sh
 CMD [ "/run.sh" ]
 ```
-`config.json`:
+### The `config.yaml` file
-```json
+This is your add-on configuration, which tell the Supervisor what to do and how to present your add-on.
-{
+
-  "name": "Hello world",
+For an overview of all valid add-on configuration options have a look [here](/docs/add-ons/configuration#add-on-configuration)
-  "version": "1",
+
-  "slug": "hello_world",
+```yaml
-  "description": "My first real add-on!",
+name: "Hello world"
-  "arch": ["armhf", "armv7", "aarch64", "amd64", "i386"],
+description: "My first real add-on!"
-  "startup": "application",
+version: "1.0.0"
-  "boot": "auto",
+slug: "hello_world"
-  "options": {},
+arch:
-  "schema": {}
+  - aarch64
-}
+  - amd64
  - armhf
  - armv7
  - i386
 ```
-`run.sh`:
+### The `run.sh` file
 This is the script that will run when your add-on starts.
 ```shell
 #!/usr/bin/with-contenv bashio
-echo Hello world!
+echo "Hello world!"
 ```
 :::note
 Make sure your editor is using UNIX-like line breaks (LF), not Dos/Windows (CRLF).
 :::
 ## Step 2: Installing and testing your add-on
 Now comes the fun part, time to open the Home Assistant UI and install and run your add-on.
 - Open the Home Assistant frontend
- Go to the Supervisor panel
+- Go to "Configuration"
- On the top right click the shopping basket to go to the add-on store.
+- Click on "Add-ons, backups & Supervisor"
 - Click "add-on store" in the bottom right corner.
-![Screenshot of the Home Assistant Supervisor main panel](/img/en/hass.io/screenshots/main_panel_addon_store.png)
+[![Open your Home Assistant instance and show the Supervisor add-on store.](https://my.home-assistant.io/badges/supervisor_store.svg)](https://my.home-assistant.io/redirect/supervisor_store/)
 - On the top right overflow menu, click the "Reload" button
- You should now see a new card called "Local" that lists your add-on!
+- You should now see a new section at the top of the store called "Local add-ons" that lists your add-on!
 ![Screenshot of the local repository card](/img/en/hass.io/screenshots/local_repository.png)
 - Click on your add-on to go to the add-on details page.
 - Install your add-on
 - Start your add-on
- Refresh the logs of your add-on, you should now see "Hello world!" in your logs.
+- Click on the "Logs" tab, and refresh the logs of your add-on, you should now see "Hello world!" in your logs.
 ![Screenshot of the add-on logs](/img/en/hass.io/tutorial/addon_hello_world_logs.png)
@ -92,7 +99,7 @@ Now comes the fun part, time to open the Home Assistant UI and install and run y
 Oops! You clicked "Reload" in the store and your add-on didn't show up. Or maybe you just updated an option, clicked refresh and saw your add-on disappear.
-When this happens, it means that your `config.json` is invalid. It's either invalid JSON or one of the specified options is incorrect. To see what went wrong, go to the Supervisor panel and in the supervisor card click on "View logs". This should bring you to a page with the logs of the supervisor. Scroll to the bottom and you should be able to find the validation error.
+When this happens, it means that your `config.yaml` is invalid. It's either [invalid YAML](http://www.yamllint.com/) or one of the specified options is incorrect. To see what went wrong, go to the Supervisor panel and in the supervisor card click on "View logs". This should bring you to a page with the logs of the supervisor. Scroll to the bottom and you should be able to find the validation error.
 Once you fixed the error, go to the add-on store and click "Reload" again.
@ -103,7 +110,7 @@ Until now we've been able to do some basic stuff, but it's not very useful yet.
 To do this, we will need to update our files as follows:
 - `Dockerfile`: Install Python 3
- `config.json`: Make the port from the container available on the host
+- `config.yaml`: Make the port from the container available on the host
 - `run.sh`: Run the Python 3 command to start the HTTP server
 Update your `Dockerfile`:
@ -112,10 +119,10 @@ Update your `Dockerfile`:
 ARG BUILD_FROM
 FROM $BUILD_FROM
 ENV LANG C.UTF-8
 # Install requirements for add-on
-RUN apk add --no-cache python3
+RUN \
  apk add --no-cache \
    python3
 # Python 3 HTTP Server serves the current working dir
 # So let's set it to our add-on persistent data directory.
@ -128,23 +135,22 @@ RUN chmod a+x /run.sh
 CMD [ "/run.sh" ]
 ```
-Add "ports" to `config.json`. This will make TCP on port 8000 inside the container available on the host on port 8000.
+Add "ports" to `config.yaml`. This will make TCP on port 8000 inside the container available on the host on port 8000.
-```json
+```yaml
-{
+name: "Hello world"
-  "name": "Hello world",
+description: "My first real add-on!"
-  "version": "0.2",
+version: "1.1.0"
-  "slug": "hello_world",
+slug: "hello_world"
-  "description": "My first real add-on!",
+arch:
-  "arch": ["armhf", "armv7", "aarch64", "amd64", "i386"],
+  - aarch64
-  "startup": "before",
+  - amd64
-  "boot": "auto",
+  - armhf
-  "options": {},
+  - armv7
-  "schema": {},
+  - i386
-  "ports": {
+startup: before
-    "8000/tcp": 8000
+ports:
-  }
+  8000/tcp: 8000
 }
 ```
 Update `run.sh` to start the Python 3 server:
@ -152,14 +158,14 @@ Update `run.sh` to start the Python 3 server:
 ```shell
 #!/usr/bin/with-contenv bashio
-echo Hello world!
+echo "Hello world!"
 python3 -m http.server 8000
 ```
 ## Step 4: Installing the update
-Since we updated the version number in our `config.json`, Home Assistant will show an update button when looking at the add-on details. You might have to refresh your browser or click the "Reload" button in the add-on store for it to show up. If you did not update the version number, you can also uninstall and install the add-on again. After installing the add-on again, make sure you start it.
+Since we updated the version number in our `config.yaml`, Home Assistant will show an update button when looking at the add-on details. You might have to refresh your browser or click the "Reload" button in the add-on store for it to show up. If you did not update the version number, you can also uninstall and install the add-on again. After installing the add-on again, make sure you start it.
 Now navigate to [http://homeassistant.local:8000](http://homeassistant.local:8000) to see our server in action!
@ -167,35 +173,31 @@ Now navigate to [http://homeassistant.local:8000](http://homeassistant.local:800
 ## Bonus: Working with add-on options
-In the screenshot you've probably seen that our server only served up 1 file: `options.json`. This file contains the user configuration for this add-on. Because we specified an empty "config" and "schema" in our `config.json`, the file is currently empty.
+In the screenshot you've probably seen that our server only served up 1 file: `options.json`. This file contains the user configuration for this add-on. Because we specified an empty "config" and "schema" in our `config.yaml`, the file is currently empty.
 Let's see if we can get some data into that file!
-To do this, we need to specify the default options and a schema for the user to change the options.
+To do this, we need to specify the default options and a schema for the user to change the options. Change the options and schema entries in your `config.yaml` with the following:
-Change the options and schema entries in your `config.json` with the following:
+```yaml
-
+...
-```json
+options:
-{
+  beer: true
-  …
+  wine: true
-
+  liquor: false
-  "options": {
+  name: "world"
-    "beer": true,
+  year: 2017
-    "wine": true,
+schema:
-    "liquor": false,
+  beer: bool
-    "name": "world",
+  wine: bool
-    "year": 2017
+  liquor: bool
-  },
+  name: str
-  "schema": {
+  year: int
-    "beer": "bool",
+...
    "wine": "bool",
    "liquor": "bool",
    "name": "str",
    "year": "int"
  },
  …
 }
 ```
 Reload the add-on store and re-install your add-on. You will now see the options available in the add-on config screen. When you now go back to our Python 3 server and download `options.json`, you'll see the options you set. [Example of how options.json can be used inside `run.sh`](https://github.com/home-assistant/addons/blob/master/dhcp_server/data/run.sh#L10-L13)
 ## Bonus: Template add-on repository
 We maintain a full template example repository for add-ons you can use to get started. You can find that in the [`home-assistant/addons-example` repository](https://github.com/home-assistant/addons-example).
--- a/docs/api/supervisor/endpoints.md
+++ b/docs/api/supervisor/endpoints.md
@ -960,18 +960,20 @@ Update options for Home Assistant, you need to supply at least one of the payloa
 You need to call `/core/restart` after updating the options.
 :::tip
-Passing `image` with `null` and `version_latest` with `null` resets these options.
+Passing `image`, `refresh_token`, `audio_input` or `audio_output` with `null` resets the option.
 :::
 **Payload:**
 | key            | type           | description                         |
 | -------------- | -------------- | ----------------------------------- |
-| image          | string         | Name of custom image or null        |
+| boot           | boolean        | Start Core on boot                  |
-| version_latest | string or null | Optional for custom image or null   |
+| image          | string or null | Name of custom image                |
-| port           | string         | The port that Home Assistant run on |
+| port           | int            | The port that Home Assistant run on |
-| ssl            | boolean        | `true` if SSL is enabled            |
+| ssl            | boolean        | `true` to enable SSL                |
-| watchdog       | boolean        | `true` if watchdog is enabled       |
+| watchdog       | boolean        | `true` to enable the watchdog       |
 | wait_boot      | int            | Time to wait for Core to startup    |
 | refresh_token  | string or null | Token to authenticate with Core     |
 | audio_input    | string or null | Profile name for audio input        |
 | audio_output   | string or null | Profile name for audio output       |
@ -2268,6 +2270,54 @@ Returns information about the security features
 ### Supervisor
 <ApiEndpoint path="/supervisor/available_updates" method="get">
 Returns information about available updates
 **Example response:**
 ```json
 {
  "available_updates": [
  {
      "panel_path": "/update-available/core",
      "update_type": "core",
      "version_latest": "321",
    },
    {
      "panel_path": "/update-available/os",
      "update_type": "os",
      "version_latest": "321",
    },
    {
      "panel_path": "/update-available/supervisor",
      "update_type": "supervisor",
      "version_latest": "321",
    },
    {
      "name": "Awesome addon",
      "icon": "/addons/awesome_addon/icon",
      "panel_path": "/update-available/awesome_addon",
      "update_type": "addon",
      "version_latest": "321",
    }
  ]
 }
 ```
 **Returned data:**
 | key | type | description |
 -- | -- | --
 update_type | string | `addon`, `os`, `core` or `supervisor`
 name | string | Returns the name (only if the `update_type` is `addon`)
 icon | string | Returns the path for the icon if any (only if the `update_type` is `addon`)
 version_latest | string | Returns the available version
 panel_path | string | Returns path where the UI can be loaded
 </ApiEndpoint>
 <ApiEndpoint path="/supervisor/info" method="get">
 Returns information about the supervisor
--- a/docs/config_entries_config_flow_handler.md
+++ b/docs/config_entries_config_flow_handler.md
@ -212,10 +212,9 @@ async def async_migrate_entry(hass, config_entry: ConfigEntry):
        new = {**config_entry.data}
        # TODO: modify Config Entry data
        config_entry.data = {**new}
        config_entry.version = 2
        hass.config_entries.async_update_entry(config_entry, data=new)
    _LOGGER.info("Migration to version %s successful", config_entry.version)
--- a/docs/core/entity.md
+++ b/docs/core/entity.md
@ -7,7 +7,7 @@ For a generic introduction of entities, see [entities architecture](../architect
 ## Basic implementation
-Below is an example switch entity that keeps track of their state in memory.
+Below is an example switch entity that keeps track of its state in memory.
 ```python
 from homeassistant.components.switch import SwitchEntity
@ -50,7 +50,7 @@ With polling, Home Assistant will ask the entity from time to time (depending on
 When you subscribe to updates, your code is responsible for letting Home Assistant know that an update is available. Make sure you have the `should_poll` property return `False`.
-Whenever you receive new state from your subscription, you can tell Home Assistant that an update is available by calling `schedule_update_ha_state()` or async callback `async_schedule_update_ha_state()`. Pass in the boolean `True` to the method if you want Home Assistant to call your update method before writing the update to Home Assistant.
+Whenever you receive a new state from your subscription, you can tell Home Assistant that an update is available by calling `schedule_update_ha_state()` or async callback `async_schedule_update_ha_state()`. Pass in the boolean `True` to the method if you want Home Assistant to call your update method before writing the update to Home Assistant.
 ## Generic properties
@ -125,8 +125,8 @@ class MySwitch(SwitchEntity):
 ```python
 class MySwitch(SwitchEntity):
-    def __init(self, icon: str) -> None:
+    def __init__(self, icon: str) -> None:
-        _attr_icon = icon
+        self._attr_icon = icon
    ...
 ```
--- a/docs/core/entity/button.md
+++ b/docs/core/entity/button.md
@ -0,0 +1,50 @@
 ---
 title: Button Entity
 sidebar_label: Button
 ---
 A button entity is an entity that can fire an event / trigger an action towards a device or service but remains stateless from the Home Assistant perspective.
 It can be compared to a real live momentary switch, push-button, or some other form of a stateless switch. It is, however, not suitable for implementing actual physical buttons; the sole purpose of a button entity is to provide a virtual button inside Home Assistant.
 A switch button entity is derived from the  [`homeassistant.components.button.ButtonEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/button/__init__.py),
 and can be helpful for controlling device features like (but not limited to):
 - Upgrading firmware
 - Reboot/Restart a device
 - Brew a cup of coffee
 - Reset something (like a counter, filter usage)
 If you want to represent something that can be turned on and off (and thus have an actual state), you should use a `switch` entity instead. If you want to integrate a real, physical, stateless button device in Home Assistant, you can do so by firing custom events. The entity button entity isn't suitable for these cases.
 ## Properties
 As this integration is stateless, it doesn't provide any specific properties for itself.
 Other properties that are common to all entities such as `device_class`, `icon`, `name` etc are still applicable.
 ## Methods
 ### Press
 The press method can be used to trigger an action towards a device or service.
 It is called by Home Assistant when the user presses the button or the
 service to press the button has been called.
 ```python
 class MyButton(ButtonEntity):
    # Implement one of these methods.
    def press(self) -> None:
        """Handle the button press."""
    async def async_press(self) -> None:
        """Handle the button press."""
 ```
 ### Available device classes
 Optionally specifies what type of entity it is. It will possibly map to Google device types.
 | Value | Description
 | ----- | -----------
 | restart | The button entity restarts the device.
 | update | The button entity updates the software of the device.
--- a/docs/core/entity/camera.md
+++ b/docs/core/entity/camera.md
@ -20,8 +20,7 @@ Properties should always only return information from memory and not do I/O (lik
 | brand | str | None | The brand (manufacturer) of the camera.
 | model | str | None | The model of the camera.
 | frame_interval | float | 0.5 | The interval between frames of the stream.
-| frontend_stream_type | str | None | Used with `SUPPORT_STREAM` to tell the frontend which type of stream to use
+| frontend_stream_type | str | None | Used with `SUPPORT_STREAM` to tell the frontend which type of stream to use (`STREAM_TYPE_HLS` or `STREAM_TYPE_WEBRTC`)
 (`STREAM_TYPE_HLS` or `STREAM_TYPE_WEBRTC`)
 ### Supported features
--- a/docs/core/entity/fan.md
+++ b/docs/core/entity/fan.md
@ -11,10 +11,6 @@ A fan entity is a device that controls the different vectors of your fan such as
 Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
 :::
 :::caution
 FanEntity does not support attribute shorthand for [property implementation](../entity.md#entity-class-or-instance-attributes)
 :::
 | Name | Type | Default | Description
 | ---- | ---- | ------- | -----------
 | current_direction | str | None | Return the current direction of the fan |
--- a/docs/core/entity/sensor.md
+++ b/docs/core/entity/sensor.md
@ -15,7 +15,7 @@ Properties should always only return information from memory and not do I/O (lik
 | ---- | ---- | ------- | -----------
 | device_class | string | `None` | Type of sensor.
 | last_reset | `datetime.datetime` | `None` | The time when an accumulating sensor such as an electricity usage meter, gas meter, water meter etc. was initialized. If the time of initialization is unknown, set it to `None`. Note that the `datetime.datetime` returned by the `last_reset` property will be converted to an ISO 8601-formatted string when the entity's state attributes are updated. When changing `last_reset`, the `state` must be a valid number.
-| native_value | string | **Required** | The value of the sensor in the sensor's `native_unit_of_measurement`.
+| native_value | `None`, `datetime.date`, `datetime.datetime`, float, int, string | **Required** | The value of the sensor in the sensor's `native_unit_of_measurement`. Using a `device_class` may restrict the types that can be returned by this property.
 | native_unit_of_measurement | string | `None` | The unit of measurement that the sensor's value is expressed in. If the `native_unit_of_measurement` is °C or °F, and its `device_class` is temperature, the sensor's `unit_of_measurement` will be the preferred temperature unit configured by the user and the sensor's `state` will be the `native_value` after an optional unit conversion.
 | state_class | string | `None` | Type of state.
@ -31,12 +31,13 @@ If specifying a device class, your sensor entity will need to also return the co
 | carbon_dioxide | ppm | Concentration of carbon dioxide.
 | carbon_monoxide | ppm | Concentration of carbon monoxide.
 | current | A | Current
-| date | | Date, must be formatted according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601).
+| date | | Date. Requires `native_value` to be a Python `datetime.date` object, or `None`.
 | energy | Wh, kWh, MWh | Energy, statistics will be stored in kWh.
 | frequency | Hz, kHz, MHz, GHz | Frequency
 | gas | m³, ft³ | Volume of gas, statistics will be stored in m³. Gas consumption measured as energy in kWh instead of a volume should be classified as energy.
 | humidity | % | Relative humidity
 | illuminance | lx, lm | Light level
-| monetary | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Unofficial_codes_for_cryptocurrencies) | Monetary value with a currency.
+| monetary | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) | Monetary value with a currency.
 | nitrogen_dioxide | µg/m³ | Concentration of nitrogen dioxide |
 | nitrogen_monoxide | µg/m³ | Concentration of nitrogen monoxide |
 | nitrous_oxide | µg/m³ | Concentration of nitrous oxide |
@ -46,11 +47,11 @@ If specifying a device class, your sensor entity will need to also return the co
 | pm10 | µg/m³ | Concentration of particulate matter less than 10 micrometers |
 | power | W, kW | Power, statistics will be stored in W.
 | power_factor | % | Power Factor
-| pressure | bar, hPa, inHg, kPa, mbar, Pa, psi | Pressure, statistics will be stored in Pa.
+| pressure | cbar, bar, hPa, inHg, kPa, mbar, Pa, psi | Pressure, statistics will be stored in Pa.
 | signal_strength | dB, dBm | Signal strength
 | sulphur_dioxide | µg/m³ | Concentration of sulphure dioxide |
 | temperature | °C, °F | Temperature, statistics will be stored in °C.
-| timestamp | | Timestamp, must be formatted according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601).
+| timestamp | | Timestamp. Requires `native_value` to return a Python `datetime.datetime` object, with time zone information, or `None`.
 | volatile_organic_compounds | µg/m³ | Concentration of volatile organic compounds
 | voltage | V | Voltage
--- a/docs/creating_integration_file_structure.md
+++ b/docs/creating_integration_file_structure.md
@ -28,4 +28,5 @@ Home Assistant will look for an integration when it sees the domain referenced i
 - `<config directory>/custom_components/<domain>`
 - `homeassistant/components/<domain>` (built-in integrations)
-You can override a built-in integration by having an integration with the same domain in your `config/custom_components` folder. Note that overriding built-in components is not recommended as you will no longer get updates. It is recommended to pick a unique name.
+You can override a built-in integration by having an integration with the same domain in your `<config directory>/custom_components` folder. [The `manifest.json` file requires a version tag when you override a core integration](creating_integration_manifest/#version). An overridden core integration can be identified by a specific icon in the upper right corner of the integration box in the overview [![Open your Home Assistant instance and show your integrations.](https://my.home-assistant.io/badges/integrations.svg)](https://my.home-assistant.io/redirect/integrations/)
 Note that overriding built-in integrations is not recommended as you will no longer get updates. It is recommended to pick a unique name.
--- a/docs/creating_integration_manifest.md
+++ b/docs/creating_integration_manifest.md
@ -132,20 +132,19 @@ Zeroconf is a list so you can specify multiple types to match on.
 }
 ```
-Certain zeroconf types are very generic (i.e., `_printer._tcp.local.`, `_axis-video._tcp.local.` or `_http._tcp.local`). In such cases you should include a Name (`name`), MAC address (`macaddress`), Manufacturer (`manufacturer`), or Model (`model`) filter:
+Certain zeroconf types are very generic (i.e., `_printer._tcp.local.`, `_axis-video._tcp.local.` or `_http._tcp.local`). In such cases you should include a Name (`name`), or Properties (`properties`) filter:
 ```json
 {
  "zeroconf": [
-    {"type":"_axis-video._tcp.local.","macaddress":"00408C*"},
+    {"type":"_axis-video._tcp.local.","properties":{"macaddress":"00408c*"}},
    {"type":"_axis-video._tcp.local.","name":"example*"},
-    {"type":"_airplay._tcp.local.","manufacturer":"samsung*"},
+    {"type":"_airplay._tcp.local.","properties":{"am":"audioaccessory*"}},
    {"type":"_airplay._tcp.local.","manufacturer":"appletv*"},
   ]
 }
 ```
-Note that the `name`, `manufacturer`, and `model` filters should be all lowercase and the `macaddress` filter should be all uppercase.
+Note that all values in the `properties` filters must be lowercase, and may contain a fnmatch type wildcard.
 ## SSDP
--- a/docs/device_registry_index.md
+++ b/docs/device_registry_index.md
@ -32,7 +32,7 @@ Although not currently available, we could consider offering an option to users
 | default_name         | Default name of this device, will be overridden if `name` is set. Useful for example for an integration showing all devices on the network. |
 | default_manufacturer | The manufacturer of the device, will be overridden if `manufacturer` is set. Useful for example for an integration showing all devices on the network. |
 | default_model        | The model of the device, will be overridden if `model` is set. Useful for example for an integration showing all devices on the network. |
-| entry_type           | The type of entry. Possible value is `None` and `"service"`.   |
+| entry_type           | The type of entry. Possible values are `None` and `DeviceEntryType` enum members. |
 | id                   | Unique ID of device (generated by Home Assistant) |
 | identifiers          | Set of `(DOMAIN, identifier)` tuples. Identifiers identify the device in the outside world. An example is a serial number. |
 | name                 | Name of this device |
@ -40,6 +40,7 @@ Although not currently available, we could consider offering an option to users
 | model                | The model of the device. |
 | suggested_area       | The suggested name for the area where the device is located. |
 | sw_version           | The firmware version of the device.   |
 | hw_version           | The hardware version of the device.   |
 | via_device           | Identifier of a device that routes messages between this device and Home Assistant. Examples of such devices are hubs, or parent devices of a sub-device. This is used to show device topology in Home Assistant. |
 ## Defining devices
@ -89,5 +90,6 @@ device_registry.async_get_or_create(
    name=config.name,
    model=config.modelid,
    sw_version=config.swversion,
    hw_version=config.hwversion,
 )
 ```
--- a/docs/documenting/standards.md
+++ b/docs/documenting/standards.md
@ -21,7 +21,7 @@ Broadly speaking documentation should be written following Microsoft's house sty
 - The **Configuration Variables** section must use the `{% configuration %}` tag.
 - The **Configuration Variables** section is only used for YAML configuration.
- For describing **UI Variables** the `{% configuration_base %}` section can be used.
+- For describing **UI Variables** the `{% configuration_basic %}` section can be used.
 - Configuration variables must document the requirement status (`false` or `true`).
 - Configuration variables must document the default value, if any.
 - Configuration variables must document the accepted value types (see [Configuration variables details](documenting/create-page.md#configuration)).
--- a/docs/entity_registry_disabled_by.md
+++ b/docs/entity_registry_disabled_by.md
@ -5,7 +5,7 @@ sidebar_label: Disabling entities
 The entity registry tracks all entities with unique IDs. For each entity, the registry keeps track of options that impact how the entity interacts with the core. One of these options is `disabled_by`.
-When `disabled_by` is set to a string value, the entity will not be added to Home Assistant when the integration passes it to `async_add_entities`.
+When `disabled_by` is set and not `None`, the entity will not be added to Home Assistant when the integration passes it to `async_add_entities`.
 ## Integration Architecture
@ -15,21 +15,21 @@ Entity disabling works with entities provided via a config entry or via an entry
 ## Users editing the entity registry
-One way an entity can be disabled is by the user editing the entity registry via the UI. In this case, the `disabled_by` value will be set to `user`. This will only work with entities that are already registered.
+One way an entity can be disabled is by the user editing the entity registry via the UI. In this case, the `disabled_by` value will be set to `RegistryEntryDisabler.USER`. This will only work with entities that are already registered.
 ## Integrations setting default value of disabled_by for new entity registry entries
 As an integration you can control if your entity is enabled when it is first registered. This is controlled by the `entity_registry_enabled_default` property. It defaults to `True`, which means the entity will be enabled.
-If the property returns `False`, the `disabled_by` value of the newly registered entity will be set to `integration`.
+If the property returns `False`, the `disabled_by` value of the newly registered entity will be set to `RegistryEntryDisabler.INTEGRATION`.
 ## Config entry system options setting default value of disabled_by for new entity registry entries
 The user can also control how new entities that are related to a config entry are received by setting the system option `disable_new_entities` of a config entry to `True`. This can be done via the UI.
-If an entity is getting registered and this system option is set to `True`, the `disabled_by` property will be initialized as `config_entry`.
+If an entity is getting registered and this system option is set to `True`, the `disabled_by` property will be initialized as `RegistryEntryDisabler.CONFIG_ENTRY`.
-If `disable_new_entities` is set to `True` and `entity_registry_enabled_default` returns `False`, the `disabled_by` value will be set to `integration`.
+If `disable_new_entities` is set to `True` and `entity_registry_enabled_default` returns `False`, the `disabled_by` value will be set to `RegistryEntryDisabler.INTEGRATION`.
 ## Integrations offering options to control disabled_by
--- a/package.json
+++ b/package.json
@ -12,8 +12,8 @@
  },
  "dependencies": {
    "by-node-env": "^2.0.1",
-    "@docusaurus/preset-classic": "^2.0.0-beta.8",
+    "@docusaurus/preset-classic": "^2.0.0-beta.13",
-    "@docusaurus/core": "^2.0.0-beta.8",
+    "@docusaurus/core": "^2.0.0-beta.13",
    "@mdx-js/react": "^1.6.21",
    "clsx": "^1.1.1",
    "react": "^17.0.2",
--- a/sidebars.js
+++ b/sidebars.js
@ -158,6 +158,7 @@ module.exports = {
      "core/entity/air-quality",
      "core/entity/alarm-control-panel",
      "core/entity/binary-sensor",
      "core/entity/button",
      "core/entity/camera",
      "core/entity/climate",
      "core/entity/cover",
--- a/static/img/en/architecture/component-interaction.svg
+++ b/static/img/en/architecture/component-interaction.svg
--- a/static/img/en/architecture/entity-core-interaction.svg
+++ b/static/img/en/architecture/entity-core-interaction.svg
--- a/static/img/en/architecture/entity-data-hierarchy.svg
+++ b/static/img/en/architecture/entity-data-hierarchy.svg
--- a/static/img/en/architecture/full.svg
+++ b/static/img/en/architecture/full.svg
--- a/static/img/en/architecture/integrating-devices-services.svg
+++ b/static/img/en/architecture/integrating-devices-services.svg
--- a/static/img/en/blog/2021-10-26-config-entity/configuration_url.png
+++ b/static/img/en/blog/2021-10-26-config-entity/configuration_url.png
--- a/static/img/en/hass.io/screenshots/local_repository.png
+++ b/static/img/en/hass.io/screenshots/local_repository.png
--- a/static/img/en/hass.io/screenshots/main_panel_addon_store.png
+++ b/static/img/en/hass.io/screenshots/main_panel_addon_store.png
--- a/static/img/en/hass.io/tutorial/addon_hello_world_logs.png
+++ b/static/img/en/hass.io/tutorial/addon_hello_world_logs.png
--- a/static/img/en/hass.io/tutorial/samba.png
+++ b/static/img/en/hass.io/tutorial/samba.png
--- a/static/img/en/hass.io/tutorial/ssh.png
+++ b/static/img/en/hass.io/tutorial/ssh.png
--- a/yarn.lock
+++ b/yarn.lock