YAML syntax: add headings and tiny rephrase

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
 

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

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