From b0f44235cfad9f3aa1540f34cd175073ad371d2b Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Mon, 22 Apr 2024 08:09:28 +0200 Subject: [PATCH] YAML syntax: add headings and tiny rephrase (#32361) * YAML syntax: add headings and tiny rephrase * Add related link to automation.yaml file * Remove section on secrets, add link to secrets page instead --- source/_docs/configuration.markdown | 1 + source/_docs/configuration/secrets.markdown | 5 ++ source/_docs/configuration/yaml.markdown | 53 ++++++++++++++++----- 3 files changed, 46 insertions(+), 13 deletions(-) diff --git a/source/_docs/configuration.markdown b/source/_docs/configuration.markdown index d503d326935..4589d8acff0 100644 --- a/source/_docs/configuration.markdown +++ b/source/_docs/configuration.markdown @@ -54,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 ea30432c3af..3e4eade924a 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/) diff --git a/source/_docs/configuration/yaml.markdown b/source/_docs/configuration/yaml.markdown index b59f31dd0c5..4a957fceba2 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 -
+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. -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 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,26 @@ 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/) + +### Automation + +- [Automation.yaml](/docs/automation/yaml/) \ No newline at end of file