Merge branch 'current' into next

source/_docs/configuration/splitting_configuration.markdown

@@ -6,7 +6,7 @@ redirect_from: /topics/splitting_configuration/
 
 So you've been using Home Assistant for a while now and your configuration.yaml file brings people to tears or you simply want to start off with the distributed approach, here's how to "split the configuration.yaml" into more manageable (read: humanly readable) pieces.
 
-First off, several community members have sanitized (read: without api keys/passwords etc) versions of their configurations available for viewing, you can see a list of them [here](/cookbook/#example-configurationyaml).
+First off, several community members have sanitized (read: without API keys/passwords etc) versions of their configurations available for viewing, you can see a list of them [here](/cookbook/#example-configurationyaml).
 
 As commenting code doesn't always happen, please read on for the details.
 
@@ -56,6 +56,7 @@ zwave:
 mqtt:
   broker: 127.0.0.1
 ```
+
 As with the core snippet, indentation makes a difference. The integration headers (`mqtt:`) should be fully left aligned (aka no indent), and the parameters (`broker:`) should be indented two (2) spaces.
 
 While some of these integrations can technically be moved to a separate file they are so small or "one off's" where splitting them off is superfluous. Also, you'll notice the # symbol (hash/pound). This represents a "comment" as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored. This makes breaking up files for human readability really convenient, not to mention turning off features while leaving the entry intact.
@@ -148,18 +149,20 @@ That about wraps it up.
 
 If you have issues checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to our [Discord chat server][discord] and ask away.
 
-### Debugging multiple configuration files
+## Debugging multiple configuration files
 
 If you have many configuration files, the `check_config` script allows you to see how Home Assistant interprets them:
+
 - Listing all loaded files: `hass --script check_config --files`
 - Viewing a component's config: `hass --script check_config --info light`
 - Or all components' config:  `hass --script check_config --info all`
 
 You can get help from the command line using: `hass --script check_config --help`
 
-### Advanced Usage
+## Advanced Usage
 
 We offer four advanced options to include whole directories at once. Please note that your files must have the `.yaml` file extension; `.yml` is not supported.
+
 - `!include_dir_list` will return the content of a directory as a list with each file content being an entry in the list. The list entries are ordered based on the alphanumeric ordering of the names of the files.
 - `!include_dir_named` will return the content of a directory as a dictionary which maps filename => content of file.
 - `!include_dir_merge_list` will return the content of a directory as a list by merging all files (which should contain a list) into 1 big list.
@@ -182,7 +185,7 @@ These work recursively. As an example using `!include_dir_* automation`, will in
     └── configuration.yaml (not included)
 ```
 
-#### Example: `!include_dir_list`
+### Example: `!include_dir_list`
 
 `configuration.yaml`
 
@@ -244,7 +247,7 @@ It is important to note that each file must contain only **one** entry when usin
 It is also important to note that if you are splitting a file after adding -id: to support the automation UI,
 the -id: line must be removed from each of the split files.
 
-#### Example: `!include_dir_named`
+### Example: `!include_dir_named`
 
 `configuration.yaml`
 
@@ -321,7 +324,7 @@ speech:
     {% endif %}{% endraw %}
 ```
 
-#### Example: `!include_dir_merge_list`
+### Example: `!include_dir_merge_list`
 
 `configuration.yaml`
 
@@ -376,7 +379,7 @@ automation: !include_dir_merge_list automation/
 
 It is important to note that when using `!include_dir_merge_list`, you must include a list in each file (each list item is denoted with a hyphen [-]). Each file may contain one or more entries.
 
-#### Example: `!include_dir_merge_named`
+### Example: `!include_dir_merge_named`
 
 `configuration.yaml`
 

source/_docs/configuration/troubleshooting.markdown

@@ -10,22 +10,22 @@ Before we dive into common issues, make sure you know where your configuration d
 
 Whenever an integration or configuration option results in a warning, it will be stored in `home-assistant.log` in the configuration directory. This file is reset on start of Home Assistant.
 
-### My integration does not show up
+## My integration does not show up
 
 When an integration does not show up, many different things can be the case. Before you try any of these steps, make sure to look at the `home-assistant.log` file and see if there are any errors related to your integration you are trying to set up.
 
 If you have incorrect entries in your configuration files you can use the [`check_config`](/docs/tools/check_config/) script to assist in identifying them: `hass --script check_config`. If you need to provide the path for your configuration you can do this using the `-c` argument like this: `hass --script check_config -c /path/to/your/config/dir`.
 
-#### Problems with the configuration
+### Problems with the configuration
 
-One of the most common problems with Home Assistant is an invalid `configuration.yaml` or other configuration file. 
- 
- - You can test your configuration using the command line with: `hass --script check_config`.
-   - On Hass.io you can use the [hassio command](/hassio/commandline/#home-assistant): `hassio homeassistant check`.
-   - On Docker you can use `docker exec home-assistant python -m homeassistant --script check_config --config /config` - where `home-assistant` is the name of the container.
- - The configuration files, including `configuration.yaml` must be UTF-8 encoded. If you see error like `'utf-8' codec can't decode byte`, edit the offending configuration and re-save it as UTF-8.
- - You can verify your configuration's yaml structure using [this online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.com/).
- - To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack (the examples there are specific to SaltStack, but do explain YAML issues well).
+One of the most common problems with Home Assistant is an invalid `configuration.yaml` or other configuration file.
+
+- You can test your configuration using the command line with: `hass --script check_config`.
+  - On Hass.io you can use the [`hassio` command](/hassio/commandline/#home-assistant): `hassio homeassistant check`.
+  - On Docker you can use `docker exec home-assistant python -m homeassistant --script check_config --config /config` - where `home-assistant` is the name of the container.
+- The configuration files, including `configuration.yaml` must be UTF-8 encoded. If you see error like `'utf-8' codec can't decode byte`, edit the offending configuration and re-save it as UTF-8.
+- You can verify your configuration's yaml structure using [this online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.com/).
+- To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack (the examples there are specific to SaltStack, but do explain YAML issues well).
 
 `configuration.yaml` does not allow multiple sections to have the same name. If you want to load multiple platforms for one component, you can append a [number or string](/getting-started/devices/#style-2-list-each-device-separately) to the name or nest them using [this style](/getting-started/devices/#style-1-collect-every-entity-under-the-parent):
 
@@ -55,13 +55,14 @@ It can happen that some integrations either do not work right away or stop worki
 
 #### Multiple files
 
-If you are using multiple files for your setup, make sure that the pointers are correct and the format of the files is valid. 
+If you are using multiple files for your setup, make sure that the pointers are correct and the format of the files is valid.
 
 ```yaml
 light: !include devices/lights.yaml
 sensor: !include devices/sensors.yaml
 ```
-Contents of `lights.yaml` (notice it does not contain `light: `):
+
+Contents of `lights.yaml` (notice it does not contain `light:`):
 
 ```yaml
 - platform: hyperion
@@ -89,8 +90,8 @@ Whenever you report an issue, be aware that we are volunteers who do not have ac
 
 The only characters valid in entity names are:
 
-* Lowercase letters
-* Numbers
-* Underscores
+- Lowercase letters
+- Numbers
+- Underscores
 
 If you create an entity with other characters then Home Assistant may not generate an error for that entity. However you will find that attempts to use that entity will generate errors (or possibly fail silently).

source/_docs/ecosystem/backup/backup_dropbox.markdown

@@ -4,9 +4,9 @@ description: "Instructions on how backup your Home Assistant configuration to Dr
 redirect_from: /cookbook/dropboxbackup/
 ---
 
-Backing up and regularly syncing your Home Assistant configuration to [Dropbox](http://dropbox.com) is similar to [Github Backup](/docs/ecosystem/backup/backup_github/)
+Backing up and regularly syncing your Home Assistant configuration to [Dropbox](http://dropbox.com) is similar to [GitHub Backup](/docs/ecosystem/backup/backup_github/)
 
-### Requirements
+## Requirements
 
 You need two parts in order to get it working correctly.
 
@@ -25,6 +25,7 @@ In the Python script you can specify which files and directories should be exclu
 chmod +x dropbox_uploader.sh
 ./dropbox_uploader.sh
 ```
+
 Follow the instructions you see on your screen.
 
 ### Step 2: Running the Dropbox uploader
@@ -35,18 +36,20 @@ Go to the folder you have placed `dropbox.py`.
   Copy file `dropbox_uploader.sh` to : `.homeassistant/extraconfig/shell_code/` (so the full path would be similar to: `/home/homeassistant/.homeassistant/extraconfig/shell_code/dropbox_uploader.sh`)
 - **Option B:**
   Edit `dropbox.py`:
-  Change the following line: 
+  Change the following line:
+
   ```txt
   uploader = "/home/homeassistant/.homeassistant/extraconfig/shell_code/dropbox_uploader.sh"
   ```
+
   to where you placed your file: (for example):
+
   ```txt
   uploader = "/home/homeassistant/MyFolder/dropbox_uploader.sh"
   ```
 
-
 ```bash
-$ python dropbox.py
+python dropbox.py
 ```
 
 The first time can take a lot of time since it will upload all your files!
@@ -58,5 +61,5 @@ So you just made a full backup, next time you want it to be done automatically.
 Add it to your crontab, edit the **path/to** part.
 
 ```bash
-$ (crontab -l 2>/dev/null; echo "0 3 * * * python /path/to/dropbox.py") | crontab -
+(crontab -l 2>/dev/null; echo "0 3 * * * python /path/to/dropbox.py") | crontab -
 ```

source/_docs/z-wave/devices.markdown

@@ -4,7 +4,7 @@ description: "What you need to know about Z-Wave devices."
 redirect_from: /getting-started/z-wave-devices/
 ---
 
-## Devices, Nodes, Entities, what?
+## Devices, Nodes, Entities
 
 The *device* is the hardware, and also used when referring to the node and all its entities. There are 3 main types of devices:
 
@@ -65,8 +65,8 @@ Polling needs to be enabled per device, you can control this through the *pollin
 
 The Central Scene command class isn't yet supported in OpenZWave (there is [work in progress](https://github.com/OpenZWave/open-zwave/pull/1125) to provide it it), though Home Assistant has introduced some support with [change 9178](https://github.com/home-assistant/home-assistant/pull/9178) which was part of 0.53 and [documented here](/docs/z-wave/device-specific/#homeseer-switches).
 
-## Is my device supported?
+## Supported Devices
 
-You can check to see if OpenZWave supports your particular device by looking at the [OpenZWave 1.4 github](https://github.com/OpenZWave/open-zwave/tree/1.4/config). Be aware that being listed here doesn't mean that it will be supported in Home Assistant, since the version of OpenZWave used by Home Assistant will often lag the github by a few months.
+You can check to see if OpenZWave supports your particular device by looking at the [OpenZWave 1.4 GitHub](https://github.com/OpenZWave/open-zwave/tree/1.4/config). Be aware that being listed here doesn't mean that it will be supported in Home Assistant, since the version of OpenZWave used by Home Assistant will often lag the GitHub by a few months.
 
 Even if your device isn't listed there, it's likely that it will still work as expected as long as the device complies with the Z-Wave standards. The OpenZWave wiki describes how [you can add support](https://github.com/OpenZWave/open-zwave/wiki/Adding-Devices) for your device if it isn't listed.

source/_docs/z-wave/installation.markdown

@@ -88,8 +88,9 @@ device_config / device_config_domain / device_config_glob:
 Security Z-Wave devices require a network key before being added to the network using the Add Secure Node button in the Z-Wave Network Management card. You must set the *network_key* configuration variable to use a network key before adding these devices.
 
 An easy script to generate a random key:
+
 ```bash
-$ cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g' -e 's/, $//'
+cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0x\1, /g' -e 's/, $//'
 ```
 
 You can also use sites like [this one](https://www.random.org/cgi-bin/randbyte?nbytes=16&format=h) to generate the required data, just remember to put `0x` before each pair of characters:
@@ -116,10 +117,10 @@ You do not need to install any software to use Z-Wave.
 
 If the path of `/dev/ttyACM0` doesn't work, look in the *System* section of the *Hass.io* menu. There you'll find a *Hardware* button which will list all the hardware found.
 
-You can also check what hardware has been found using the [hassio command](/hassio/commandline/#hardware):
+You can also check what hardware has been found using the [`hassio` command](/hassio/commandline/#hardware):
 
 ```bash
-$ hassio hardware info
+hassio hardware info
 ```
 
 If you did an alternative install of Hass.io on Linux (e.g. installing Ubuntu, then Docker, then Hass.io) then the `modemmanager` package will interfere with any Z-Wave (or Zigbee) stick and should be removed or disabled in the host OS. Failure to do so will result in random failures of those components, e.g. dead or unreachable Z-Wave nodes, most notably right after Home Assistant restarts. Connect to your host OS via SSH, then you can disable with `sudo systemctl disable ModemManager` and remove with `sudo apt-get purge modemmanager` (commands are for Debian/Ubuntu).
@@ -131,7 +132,7 @@ You do not need to install any software to use Z-Wave.
 To enable access to the Z-Wave stick, add `--device=/dev/ttyACM0` to the `docker` command that starts your container, for example:
 
 ```bash
-$ docker run -d --name="home-assistant" -v /home/pi/homeassistant:/config -v /etc/localtime:/etc/localtime:ro --net=host --device=/dev/ttyACM0 homeassistant/raspberrypi3-homeassistant
+docker run -d --name="home-assistant" -v /home/pi/homeassistant:/config -v /etc/localtime:/etc/localtime:ro --net=host --device=/dev/ttyACM0 homeassistant/raspberrypi3-homeassistant
 ```
 
 If the path of `/dev/ttyACM0` doesn't work then you can find the path of the stick by disconnecting and then reconnecting it, and running the following in the Docker host:
@@ -153,7 +154,7 @@ On the Raspberry Pi you will need to enable the serial interface in the `raspi-c
 On Debian Linux platforms there are dependencies you will need to have installed ahead of time (included in `systemd-devel` on Fedora/RHEL systems):
 
 ```bash
-$ sudo apt-get install libudev-dev build-essential
+sudo apt-get install libudev-dev build-essential
 ```
 
 You may also have to install the Python development libraries for your version of Python. For example `libpython3.6-dev`, and possibly `python3.6-dev` if you're using Python 3.6.
@@ -183,17 +184,18 @@ dmesg | grep USB
 If Home Assistant (`hass`) runs with another user (e.g., *homeassistant*) you need to give access to the stick with:
 
 ```bash
-$ sudo usermod -aG dialout homeassistant
+sudo usermod -aG dialout homeassistant
 ```
 
 The output from `ls -ltr` above contains the following information:
-* The device type is `c` (character special)
-* The permissions are `rw-rw----`, meaning only the owner and group can read and write to it
-* There is only `1` link to the file
-* It is owned by `root` and can be accessed by members of the group `dialout`
-* It has a major device number of `204`, and a minor device number of `64`
-* The device was connected at `10:25` on `21 September`
-* The device is `/dev/ttyUSB0`.
+
+- The device type is `c` (character special).
+- The permissions are `rw-rw----`, meaning only the owner and group can read and write to it.
+- There is only `1` link to the file.
+- It is owned by `root` and can be accessed by members of the group `dialout`.
+- It has a major device number of `204`, and a minor device number of `64`.
+- The device was connected at `10:25` on `21 September`.
+- The device is `/dev/ttyUSB0`.
 
 #### macOS
 
@@ -218,6 +220,7 @@ If your device path changes when you restart, see [this guide](http://hintshop.l
 ### Random unreachable Z-Wave nodes: ModemManager interference
 
 If this applies to your situation:
+
 - Some or all Z-Wave nodes are unreachable after restarting Home Assistant; not necessarily after every restart but seemingly random.
 - The Z-Wave stick stops responding, needs to be re-plugged or Home Assistant needs a restart to get Z-Wave back.
 - Your host OS is Debian-based/Ubuntu (for example: you installed Ubuntu, then Docker, then Hass.io).
@@ -267,7 +270,9 @@ sudo usermod -aG dialout homeassistant
 
 If you're getting errors like:
 
-    openzwave-embed/open-zwave-master/libopenzwave.a: No such file or directory
+```txt
+openzwave-embed/open-zwave-master/libopenzwave.a: No such file or directory
+```
 
 Then the problem is that you're missing `libudev-dev` (or the equivalent for your distribution), please [install it](/docs/z-wave/installation/#linux).
 

source/_faq/missing-documentation.markdown

@@ -4,7 +4,6 @@ description: "The docs are missing or outdated"
 ha_category: Documentation
 ---
 
-
 Home Assistant is a FAST moving open source project. This means occasionally the official documentation will not be 100% current or complete. Since this is an open source volunteer project, we would encourage anyone who finds gaps in the documentation to click the `edit this page on Github` link in the top right and submit any corrections/enhancements they may find useful.
 
-In the absence of information, many users find it beneficial to look at other people's configurations to find examples of what they want to accomplish in their own configurations. The easiest way to find these configurations is through this [Github search](https://github.com/search?q=topic%3Ahome-assistant-config&type=Repositories).
+In the absence of information, many users find it beneficial to look at other people's configurations to find examples of what they want to accomplish in their own configurations. The easiest way to find these configurations is through this [GitHub search](https://github.com/search?q=topic%3Ahome-assistant-config&type=Repositories).

source/_integrations/alexa.markdown

@@ -21,9 +21,12 @@ For Home Assistant Cloud Users, documentation can be found [here](https://www.na
 
 There are a few ways that you can use Amazon Alexa and Home Assistant together.
 
-- [Build custom commands](/integrations/alexa.intent/)
+- [Create an Alexa Smart Home Skill to control lights, etc.](/integrations/alexa.smart_home/)
+  - Supports utterances without requiring the skill name, such as "Alexa, turn off the light."
+  - Support for controlling devices through Alexa routines.
+  - Support for viewing and controlling devices with the Alexa mobile app.
+- [Create a Custom Alexa Skill to build custom commands](/integrations/alexa.intent/)
 - [Create a new Flash Briefing source](/integrations/alexa.flash_briefings/)
-- [Use the Smart Home API to control lights, etc.](/integrations/alexa.smart_home/)
 - Alternative: use the [Emulated Hue integration][emulated-hue-component] to trick Alexa into thinking Home Assistant is a Philips Hue hub.
 
 ### Requirements