From bba64419ded7379d8271cea12c54160e4e0d8030 Mon Sep 17 00:00:00 2001 From: c0ffeeca7 Date: Wed, 17 Apr 2024 20:34:06 +0200 Subject: [PATCH 1/3] YAML syntax: add headings and tiny rephrase --- source/_docs/configuration.markdown | 4 ++ source/_docs/configuration/yaml.markdown | 49 +++++++++++++++++------- 2 files changed, 40 insertions(+), 13 deletions(-) diff --git a/source/_docs/configuration.markdown b/source/_docs/configuration.markdown index d503d3269354..84c6f0b97c53 100644 --- a/source/_docs/configuration.markdown +++ b/source/_docs/configuration.markdown @@ -26,6 +26,10 @@ _If you use {% term "Home Assistant Operating System" %}, you can find `configur _If you use {% term "Home Assistant Core" %} , you can find `configuration.yaml` in the config folder passed to the `hass` command (default is `~/.homeassistant`)._ +### Do not store private data in your configuration.yaml file + +Avoid storing private data (passwords, API keys, etc.) directly in your `configuration.yaml` file. Private data can be stored in either a [separate file](/docs/configuration/secrets/) or in [environmental variables](/docs/configuration/yaml/#using-environment-variables), which circumvents this security problem. + ## Reloading configuration changes Most integrations in Home Assistant that do not interact with {% term devices %} or {% term services %} can reload changes made to their configuration in `configuration.yaml`. diff --git a/source/_docs/configuration/yaml.markdown b/source/_docs/configuration/yaml.markdown index b59f31dd0c5c..0cede39328f7 100644 --- a/source/_docs/configuration/yaml.markdown +++ b/source/_docs/configuration/yaml.markdown @@ -1,13 +1,17 @@ --- -title: "YAML" -description: "Details about YAML to configure Home Assistant." +title: "YAML syntax" +description: "Details about the YAML syntax used to configure Home Assistant." --- -Home Assistant uses the [YAML](https://yaml.org/) syntax for configuration. YAML might take a while to get used to but is powerful in allowing you to express complex configurations. +Home Assistant uses the [YAML](https://yaml.org/) syntax for configuration. While most integrations can be configured through the UI, some integrations require you to edit your [`configuration.yaml`](/docs/configuration/) file to specify its settings. -While more and more integrations are configured through the UI, for some, you will add code in your [`configuration.yaml`](/docs/configuration/) file to specify its settings. +## YAML Style Guide -The following example entry assumes that you would like to set up the [notify integration](/integrations/notify) with the [pushbullet platform](/integrations/pushbullet). +This page gives a high-level introduction to the YAML syntax used in Home Assistant. For a more detailed description and more examples, refer to the [YAML Style Guide for Home Assistant developers](https://developers.home-assistant.io/docs/documenting/yaml-style-guide/). + +## A first example + +The following YAML example entry assumes that you would like to set up the [notify integration](/integrations/notify) with the [pushbullet platform](/integrations/pushbullet). ```yaml notify: @@ -21,22 +25,20 @@ notify: The basics of YAML syntax are block collections and mappings containing key-value pairs. Each item in a collection starts with a `-` while mappings have the format `key: value`. This is somewhat similar to a Hash table or more specifically a dictionary in Python. These can be nested as well. **Beware that if you specify duplicate keys, the last value for a key is used**. +## Indentation in YAML + In YAML, indentation is important for specifying relationships. Indented lines are nested inside lines that are one level higher. In the above example, `platform: pushbullet` is a property of (nested inside) the `notify` integration. Getting the right indentation can be tricky if you're not using an editor with a fixed-width font. Tabs are not allowed to be used for indentation. The convention is to use 2 spaces for each level of indentation. -To check if your YAML syntax is correct before loading it into Home Assistant, you can use the third-party service [YAML Validator](https://codebeautify.org/yaml-validator/) (not maintained by the Home Assistant community). - -
+## Comments -Pay attention to not storing private data (passwords, API keys, etc.) directly in your `configuration.yaml` file. Private data can be stored in either a [separate file](/docs/configuration/secrets/) or in [environmental variables](/docs/configuration/yaml/#using-environment-variables), which circumvents this security problem. +Strings of text following a `#` are comments. They are ignored by the system. Comments explain in plain language what a particular code block is supposed to do. For future-you or someone else looking at the file. -
- -Strings of text following a `#` are comments and are ignored by the system. +### Example with comment and nesting The next example shows an [input_select](/integrations/input_select) integration that uses a block collection for the values of options. -The other properties (like `name:`) are specified using mappings. Note that the second line just has `threat:` with no value on the same line. Here threat is the name of the input_select and the values for it are everything nested below it. +The other properties (like `name:`) are specified using mappings. Note that the second line just has `threat:` with no value on the same line. Here, `threat` is the name of the input_select. The values for it are everything nested below it. ```yaml input_select: @@ -51,6 +53,8 @@ input_select: initial: 0 ``` +### Example of nested mapping + The following example shows nesting a collection of mappings in a mapping. In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their `state_topic` (one of the properties used for MQTT sensors). ```yaml @@ -120,3 +124,22 @@ Not quoting the value may generate an error such as: ```txt not a valid value for dictionary value @ data ``` + +## Validating YAML syntax + +With all these indents and rules, it is easy to make a mistake. The best way to check if your YAML syntax is correct (validate) depends on the editor you use. We can't list them all here. + +- If you edit the files directly in Home Assistant, refer to the section: [Validating the configuration](/docs/configuration/#validating-the-configuration) + +## Related topics + +### YAML + +- [YAML Style Guide for Home Assistant developers](https://developers.home-assistant.io/docs/documenting/yaml-style-guide/) +- [Validating the configuration](/docs/configuration/#validating-the-configuration) + +### Related configuration topics + +- [`configuration.yaml` file](/docs/configuration/) +- [Troubleshooting the configuration files](/docs/configuration/troubleshooting/) +- [Storing private data in separate file](/docs/configuration/secrets/) \ No newline at end of file From 1c0a4020551cac29ad22c1bcb5cb60633cf8afa5 Mon Sep 17 00:00:00 2001 From: c0ffeeca7 Date: Wed, 17 Apr 2024 20:42:43 +0200 Subject: [PATCH 2/3] Add related link to automation.yaml file --- source/_docs/configuration/yaml.markdown | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/_docs/configuration/yaml.markdown b/source/_docs/configuration/yaml.markdown index 0cede39328f7..4a957fceba2b 100644 --- a/source/_docs/configuration/yaml.markdown +++ b/source/_docs/configuration/yaml.markdown @@ -142,4 +142,8 @@ With all these indents and rules, it is easy to make a mistake. The best way to - [`configuration.yaml` file](/docs/configuration/) - [Troubleshooting the configuration files](/docs/configuration/troubleshooting/) -- [Storing private data in separate file](/docs/configuration/secrets/) \ No newline at end of file +- [Storing private data in separate file](/docs/configuration/secrets/) + +### Automation + +- [Automation.yaml](/docs/automation/yaml/) \ No newline at end of file From 1e1d5ac1590f825b98d8e5012ba1c6459bb3155d Mon Sep 17 00:00:00 2001 From: c0ffeeca7 Date: Thu, 18 Apr 2024 09:03:57 +0200 Subject: [PATCH 3/3] Remove section on secrets, add link to secrets page instead --- source/_docs/configuration.markdown | 5 +---- source/_docs/configuration/secrets.markdown | 5 +++++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/source/_docs/configuration.markdown b/source/_docs/configuration.markdown index 84c6f0b97c53..4589d8acff05 100644 --- a/source/_docs/configuration.markdown +++ b/source/_docs/configuration.markdown @@ -26,10 +26,6 @@ _If you use {% term "Home Assistant Operating System" %}, you can find `configur _If you use {% term "Home Assistant Core" %} , you can find `configuration.yaml` in the config folder passed to the `hass` command (default is `~/.homeassistant`)._ -### Do not store private data in your configuration.yaml file - -Avoid storing private data (passwords, API keys, etc.) directly in your `configuration.yaml` file. Private data can be stored in either a [separate file](/docs/configuration/secrets/) or in [environmental variables](/docs/configuration/yaml/#using-environment-variables), which circumvents this security problem. - ## Reloading configuration changes Most integrations in Home Assistant that do not interact with {% term devices %} or {% term services %} can reload changes made to their configuration in `configuration.yaml`. @@ -58,6 +54,7 @@ The method for running a configuration check depends on your [installation type] - [YAML syntax](/docs/configuration/yaml/) - [Configuration check on Operating System](/common-tasks/os/#configuration-check) +- [Storing credentials in `secrets.yaml` file](/docs/configuration/secrets) ### Backups diff --git a/source/_docs/configuration/secrets.markdown b/source/_docs/configuration/secrets.markdown index ea30432c3af0..3e4eade924ab 100644 --- a/source/_docs/configuration/secrets.markdown +++ b/source/_docs/configuration/secrets.markdown @@ -59,3 +59,8 @@ hass --script check_config --secrets ``` This will print all your secrets. + +### Related topics + +- [`configuration.yaml` file](/docs/configuration/) +- [Splitting the configuration](/docs/configuration/splitting_configuration/)