Merge branch 'current' into patch-5

guides/configuration-types.rst

@@ -176,7 +176,24 @@ validating your configuration, ESPHome will automatically replace all occurrence
 by their value. The syntax for a substitution is based on bash and is case-sensitive: ``$substitution_key`` or
 ``${substitution_key}`` (same).
 
-Additionally, you can use the YAML ``<<`` syntax to create a single YAML file from which a number
+Two substitution passes are performed allowing compound replacements.
+
+.. code-block:: yaml
+
+    substitutions:
+      foo: yellow
+      bar_yellow_value: !secret yellow_secret
+      bar_green_value: !secret green_secret
+    
+    something:
+      test: ${bar_${foo}_value}
+
+.. _YAML-insertion-operator:
+
+YAML insertion operator
+***********************
+
+Additionally, you can use the YAML insertion operator ``<<`` syntax to create a single YAML file from which a number
 of nodes inherit:
 
 .. code-block:: yaml
@@ -210,6 +227,44 @@ of nodes inherit:
     - Place them in a subdirectory (dashboard only shows files in top-level directory)
     - Prepend a dot to the filename, like ``.base.yaml``
 
+.. _substitute-include-variables:
+
+Substitute !include variables
+*****************************
+
+ESPHome's ``!include`` accepts a list of variables that can be substituted within the included file.
+
+.. code-block:: yaml
+
+    binary_sensor:
+      - platform: gpio
+        id: button1
+        pin: GPIO16
+        on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax
+      - platform: gpio
+        id: button2
+        pin: GPIO4
+        on_multi_click: !include
+          # multi-line syntax
+          file: on-multi-click.yaml
+          vars:
+            id: 2
+            
+``on-multi-click.yaml``:
+
+.. code-block:: yaml
+
+    - timing: !include click-single.yaml 
+      then:
+        - mqtt.publish:
+            topic: ${device_name}/button${id}/status
+            payload: single
+    - timing: !include click-double.yaml
+      then:
+        - mqtt.publish:
+            topic: ${device_name}/button${id}/status
+            payload: double
+
 .. _command-line-substitutions:
 
 Command line substitutions