document include filename with substitutions

Author: jpeletier

content/components/packages.md

@@ -168,6 +168,29 @@ switch:
     # ...
 ```
 
+It is also possible to use substitutions/Jinja in include filenames, allowing to dynamically select what file is loaded:
+
+```yaml
+substitutions:
+  platform: esp32
+
+packages:
+  hardware: !include device-${platform}.yaml
+
+light:
+  - platform: status_led
+    name: "Board Status"
+    pin: LED_GPIO
+```
+
+```yaml
+# device-esp32.yaml
+substitutions:
+  LED_GPIO: 2
+esp32:
+  board: esp32dev
+```
+
 {{< anchor "config-packages_extend" >}}
 
 ## Extend

content/components/substitutions.md

@@ -169,7 +169,7 @@ In the above example, the value of the `text` property will be, literally, `This
 
 ## Substitute !include variables
 
-ESPHome's `!include` accepts a list of variables that can be substituted within the included file.
+ESPHome's `!include` accepts a list of variables that can be substituted within the included file. The file path may itself be constructed out of any expression that evaluates to a valid path.
 
 ```yaml
 binary_sensor:
@@ -180,14 +180,13 @@ binary_sensor:
   - platform: gpio
     id: button2
     pin: GPIOXX
-    on_multi_click: !include
-      # multi-line syntax
+    on_multi_click: !include # multi-line syntax
       file: on-multi-click.yaml
       vars:
         id: 2
 ```
 
-`on-multi-click.yaml`  :
+`on-multi-click.yaml` :
 
 ```yaml
 - timing: !include click-single.yaml
@@ -202,6 +201,22 @@ binary_sensor:
         payload: double
 ```
 
+You can also use substitutions to build the path of the file to be loaded:
+
+```yaml
+substitutions:
+  platform: esp32
+
+binary_sensor:
+  - platform: gpio
+      id: button2
+      pin: GPIOXX
+      on_multi_click: !include
+        file: on-multi-click-${platform}.yaml
+        vars:
+          id: 2
+```
+
 {{< anchor "command-line-substitutions" >}}
 
 ## Command line substitutions
@@ -253,12 +268,12 @@ esphome:
   # ...
 
 sensor:
-- platform: dht
-  # ...
-  temperature:
-    name: Temperature
-  humidity:
-    name: Humidity
+  - platform: dht
+    # ...
+    temperature:
+      name: Temperature
+    humidity:
+      name: Humidity
 ```
 
 ```yaml
@@ -269,6 +284,8 @@ substitutions:
 <<: !include common.yaml
 ```
 
+NOTE: using substitutions in the `!include` filename of a YAML insertion operator is not supported yet.
+
 > [!TIP]
 > To hide these base files from the dashboard, you can
 >