home-assistant · frenck · Oct 2, 2024 · Oct 2, 2024 · Oct 2, 2024 · Oct 2, 2024
diff --git a/source/_data/glossary.yml b/source/_data/glossary.yml
@@ -582,6 +582,10 @@
     Variables are used to store values in memory that can be processed for
     example, in a script.
   link: /docs/scripts/#variables
+- term: YAML
+  definition: >-
+    YAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files.
+  link: /docs/configuration/yaml/
 - term: Zone
   definition: >-
     Zones allow you to specify certain regions on a map. They enable zone presence-detection and can be used in automations. For example, to start the vacuum after you left home or start the heating at home when you leave the office.

diff --git a/source/_docs/automation/using_blueprints.markdown b/source/_docs/automation/using_blueprints.markdown
@@ -83,15 +83,15 @@ Blueprints created by the community may go through multiple revisions. Sometimes
 the community provides feedback, new functionality is added.
 
 If you do not want to [re-import the blueprint](/docs/automation/using_blueprints/#re-importing-a-blueprint) for some reason, you can manually edit
-its YAML content to keep it up to date:
+its {% term YAML %} content to keep it up to date:
 
 1. Navigate to the blueprints directory (`blueprints/automation/`).
    The location of this directory depends on the installation method. It's
    similar to how you find [`configuration.yaml`](/docs/configuration/#editing-configurationyaml).
 2. Next, you must find the blueprint to update. The path name of a blueprint consists of:
    - The username of the user that created it. The name depends on the source of the blueprint:
      the forum, or GitHub.
-   - The name of the YAML file. For the forum it's the title of the topic in the URL, for GitHub
+   - The name of the {% term YAML %} file. For the forum it's the title of the topic in the URL, for GitHub
      it's the name of the YAML file.
 3. Open the YAML file with your editor and update its contents.
 4. Reload the automations for the changes to take effect.

diff --git a/source/_docs/automation/yaml.markdown b/source/_docs/automation/yaml.markdown
@@ -3,11 +3,11 @@ title: "Automation YAML"
 description: "How to use the automation integration with YAML."
 ---
 
-Automations are created in Home Assistant via the UI, but are stored in a YAML format. If you want to edit the YAML of an {% term automation %}, select the automation, click on the menu button in the top right then on **Edit in YAML**.
+Automations are created in Home Assistant via the UI, but are stored in a {% term YAML %} format. If you want to edit the {% term YAML %} of an {% term automation %}, select the automation, click on the menu button in the top right then on **Edit in YAML**.
 
 The UI will write your automations to `automations.yaml`. This file is managed by the UI and should not be edited manually.
 
-It is also possible to write your automations directly inside {% term "`configuration.yaml`" %} or other YAML files. You can do this by adding a labeled `automation` block to your `configuration.yaml`:
+It is also possible to write your automations directly inside {% term "`configuration.yaml`" %} or other {% term YAML %} files. You can do this by adding a labeled `automation` block to your `configuration.yaml`:
 
 ```yaml
 # The configuration required for the UI to work
@@ -125,10 +125,9 @@ action:
   <img src='/images/integrations/script/script_modes.jpg'>
 </p>
 
-
 ## YAML example
 
-Example of a YAML based automation that you can add to {% term "`configuration.yaml`" %}.
+Example of a {% term YAML %} based automation that you can add to {% term "`configuration.yaml`" %}.
 
 {% raw %}
 
@@ -207,7 +206,7 @@ automation my_lights:
 
 ## Extra options
 
-When writing automations directly in YAML, you will have access to advanced options that are not available in the user interface.
+When writing automations directly in {% term YAML %}, you will have access to advanced options that are not available in the user interface.
 
 ### Automation initial state
 
@@ -223,7 +222,7 @@ automation:
 
 ### Number of debug traces stored
 
-When using YAML you can configure the number of debugging traces stored for an automation. This is controlled with the `stored_traces` option under `trace`. Set `stored_traces` to the number of traces you wish to store for the particular automation. If not specified the default value of 5 will be used.
+When using {% term YAML %} you can configure the number of debugging traces stored for an automation. This is controlled with the `stored_traces` option under `trace`. Set `stored_traces` to the number of traces you wish to store for the particular automation. If not specified the default value of 5 will be used.
 
 ```yaml
 automation:
@@ -263,7 +262,7 @@ If you want to migrate your manual automations to use the editor, you'll have to
 
 ### Deleting automations
 
-When automations remain visible in the Home Assistant dashboard, even after having deleted in the YAML file, you have to delete them in the UI.
+When automations remain visible in the Home Assistant dashboard, even after having deleted in the {% term YAML %} file, you have to delete them in the UI.
 
 To delete them completely, go to UI {% my entities title="**Settings** > **Devices & services** > **Entities**" %} and find the automation in the search field or by scrolling down.
 

diff --git a/source/_docs/configuration/packages.markdown b/source/_docs/configuration/packages.markdown
@@ -17,7 +17,7 @@ homeassistant:
 
 The package configuration can include: `switch`, `light`, `automation`, `groups`, or most other Home Assistant integrations including hardware platforms.
 
-It can be specified inline or in a separate YAML file using `!include`.
+It can be specified inline or in a separate {% term YAML %} file using `!include`.
 
 Inline example, main {% term "`configuration.yaml`" %}:
 
@@ -74,7 +74,7 @@ Integrations inside packages can only specify platform entries using configurati
 
 ## Create a packages folder
 
-One way to organize packages is to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory, you can store any number of packages in a YAML file. This entry in your {% term "`configuration.yaml`" %} will load all YAML-files in this _packages_ folder and its subfolders:
+One way to organize packages is to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory, you can store any number of packages in a {% term YAML %} file. This entry in your {% term "`configuration.yaml`" %} will load all {% term YAML %}-files in this _packages_ folder and its subfolders:
 
 ```yaml
 homeassistant:

diff --git a/source/_docs/configuration/secrets.markdown b/source/_docs/configuration/secrets.markdown
@@ -12,7 +12,7 @@ related:
 
 The {% term "`configuration.yaml`" %} file is a plain-text file, thus it is readable by anyone who has access to the file. The file contains passwords and API tokens which need to be redacted if you want to share your configuration.
 
-By using `!secret` you can remove any private information from your configuration files. This separation can also help you to keep easier track of your passwords and API keys, as they are all stored at one place and no longer spread across the {% term "`configuration.yaml`" %} file or even multiple YAML files if you [split up your configuration](/docs/configuration/splitting_configuration/).
+By using `!secret` you can remove any private information from your configuration files. This separation can also help you to keep easier track of your passwords and API keys, as they are all stored at one place and no longer spread across the {% term "`configuration.yaml`" %} file or even multiple {% term YAML %} files if you [split up your configuration](/docs/configuration/splitting_configuration/).
 
 ## Using `secrets.yaml`
 
@@ -48,7 +48,7 @@ rest_password: "YOUR_PASSWORD"
 
 When you start splitting your configuration into multiple files, you might end up with configuration in sub folders. Secrets will be resolved in this order:
 
-- A `secrets.yaml` located in the same folder as the YAML file referencing the secret,
+- A `secrets.yaml` located in the same folder as the {% term YAML %} file referencing the secret,
 - next, parent folders will be searched for a `secrets.yaml` file with the secret, stopping at the folder with the main {% term "`configuration.yaml`" %}.
 
 To see where secrets are being loaded from, you can either add an option to your `secrets.yaml` file or use the `check_config` script. The latter is only available for {% term "Home Assistant Core" %} installations given it's available through [`hass`](/docs/tools/hass/).

diff --git a/source/_docs/configuration/troubleshooting.markdown b/source/_docs/configuration/troubleshooting.markdown
@@ -30,8 +30,8 @@ One of the most common problems with Home Assistant is an invalid {% term "`conf
   - [Supervised](/common-tasks/supervised/#configuration-check)
 
 - The configuration files, including {% term "`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](https://yaml-online-parser.appspot.com/) or [YAML Validator](https://codebeautify.org/yaml-validator/).
-- To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltproject.io/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack (the examples there are specific to SaltStack, but do explain YAML issues well).
+- You can verify your configuration's {% term YAML %} structure using [this online YAML parser](https://yaml-online-parser.appspot.com/) or [YAML Validator](https://codebeautify.org/yaml-validator/).
+- To learn more about the quirks of {% term YAML %}, read [YAML IDIOSYNCRASIES](https://docs.saltproject.io/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 integration, you can append a number or string to the name or nest them:
 
@@ -100,7 +100,7 @@ The only characters valid in entity names are:
 - Numbers
 - Underscores
 
-The entity name must not start or end with an underscore. If you create an entity with other characters from the UI, Home Assistant validates the name. If you change the name directly in the YAML file, then Home Assistant may not generate an error for that entity. However, attempts to use that entity will generate errors (or possibly fail silently).
+The entity name must not start or end with an underscore. If you create an entity with other characters from the UI, Home Assistant validates the name. If you change the name directly in the {% term YAML %} file, then Home Assistant may not generate an error for that entity. However, attempts to use that entity will generate errors (or possibly fail silently).
 
 For instructions on how to change an entity name, refer to the section on [customizing entities](/docs/configuration/customizing-devices/).
 

diff --git a/source/_docs/scene.markdown b/source/_docs/scene.markdown
@@ -29,7 +29,7 @@ scene:
 
 ## How to configure your scene
 
-In the scene you define in your YAML files, please ensure you use
+In the scene you define in your {% term YAML %} files, please ensure you use
 all required parameters as listed below.
 
 {% configuration %}

diff --git a/source/_docs/scene/editor.markdown b/source/_docs/scene/editor.markdown
@@ -78,5 +78,5 @@ For example:
 ```
 
 {% note %}
-Any comments in the YAML file will be lost and templates will be reformatted when you update a scene via the editor.
+Any comments in the {% term YAML %} file will be lost and templates will be reformatted when you update a scene via the editor.
 {% endnote %}
diff --git a/source/_docs/troubleshooting_general.markdown b/source/_docs/troubleshooting_general.markdown
@@ -30,7 +30,7 @@ Recovery mode loads a minimum set of integrations to allow troubleshooting the c
 
 ### Resolution
 
-You need to identify the issue in the configuration files and fix it there. The issue could be caused by something as simple as an invalid YAML file.
+You need to identify the issue in the configuration files and fix it there. The issue could be caused by something as simple as an invalid {% term YAML %} file.
 
 - If you are running {% term "Home Assistant Operating System" %}, you can install an add-on such as Studio Code Server to edit the configuration file if needed.
 - If you are still logged in, you can [edit your configuration](/docs/configuration/#editing-configurationyaml).

diff --git a/source/_includes/common-tasks/configuration_check.md b/source/_includes/common-tasks/configuration_check.md
@@ -9,12 +9,12 @@ After changing configuration or automation files, check if the configuration is
 1. Go to {% my profile title="your user profile" %} and enable **Advanced Mode**.
 2. Go to {% my server_controls title="**Developer tools** > **YAML**" %} and in the **Configuration validation** section, select the **Check configuration** button.
    - This is to make sure there are no syntax errors before restarting Home Assistant.
-   - It checks for valid YAML and valid config structures.
+   - It checks for valid {% term YAML %} and valid config structures.
 3. If you need to do a more comprehensive configuration check, [run the check from the CLI](#to-run-a-configuration-check-from-the-cli).
 
 ### Running a configuration check from the CLI
 
-Use the following command to check if the configuration is valid. The command line configuration check validates the YAML files and checks for valid config structures, as well as some other elements.
+Use the following command to check if the configuration is valid. The command line configuration check validates the {% term YAML %} files and checks for valid config structures, as well as some other elements.
 
 ```bash
 ha core check