jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 01:06:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

YAML syntax: add headings and tiny rephrase (#32361)

Browse Source 
* YAML syntax: add headings and tiny rephrase

* Add related link to automation.yaml file

* Remove section on secrets, add link to secrets page instead
This commit is contained in:
c0ffeeca7 2024-04-22 08:09:28 +02:00 committed by GitHub
parent 76ae18067c
commit b0f44235cf
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 46 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
source/_docs/configuration.markdown
View File

@ -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

5
source/_docs/configuration/secrets.markdown
View File

@ -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/)

53
source/_docs/configuration/yaml.markdown
View File

@ -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
<div class='note'>
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.
</div>
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/)