From 5c443c01328a05d34fad3e657504cc9dfc3b7b79 Mon Sep 17 00:00:00 2001
From: mulcmu <mulcmu@users.noreply.github.com>
Date: Fri, 25 Nov 2022 12:56:30 -0500
Subject: [PATCH 1/3] expand substitution

Highlight 2 passes are performed esphome PR 3585 (https://github.com/esphome/esphome/pull/3583)

Highlight variables can be substituted when including files esphome PR 3510 (https://github.com/esphome/esphome/pull/3510)
---
 guides/configuration-types.rst | 57 +++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst
index b71f18e23..9ec1038c3 100644
--- a/guides/configuration-types.rst
+++ b/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

From 20c4e4960a573b6bbee19b9dce68b948ca3ed7d2 Mon Sep 17 00:00:00 2001
From: mulcmu <mulcmu@users.noreply.github.com>
Date: Fri, 25 Nov 2022 13:11:45 -0500
Subject: [PATCH 2/3] fix LINT errors

---
 guides/configuration-types.rst | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst
index 9ec1038c3..ff5e7cc04 100644
--- a/guides/configuration-types.rst
+++ b/guides/configuration-types.rst
@@ -179,7 +179,7 @@ by their value. The syntax for a substitution is based on bash and is case-sensi
 Two substitution passes are performed allowing compound replacements.
 
 .. code-block:: yaml
-    
+
     substitutions:
       foo: yellow
       bar_yellow_value: !secret yellow_secret
@@ -235,7 +235,7 @@ 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
@@ -254,16 +254,16 @@ ESPHome's ``!include`` accepts a list of variables that can be substituted withi
 
 .. 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
+    - 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:
 

From 5bc4c5746dbd5bb54f665af54122b3cd4f29c888 Mon Sep 17 00:00:00 2001
From: mulcmu <mulcmu@users.noreply.github.com>
Date: Fri, 25 Nov 2022 13:18:02 -0500
Subject: [PATCH 3/3] fix LINT error

---
 guides/configuration-types.rst | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst
index ff5e7cc04..620339432 100644
--- a/guides/configuration-types.rst
+++ b/guides/configuration-types.rst
@@ -236,20 +236,20 @@ ESPHome's ``!include`` accepts a list of variables that can be substituted withi
 
 .. 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
-   
+    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