Document this built-in config var

content/components/substitutions.md

@@ -142,13 +142,41 @@ lvgl:
 To see what mathematical functions ara available,
 refer to [Python math library](https://docs.python.org/3/library/math.html) documentation.
 
-### Built-in functions
+### Built-in functions and vars
 
 In addition to the Jinja expressions, ESPHome supports a number of built-in functions that can be used in substitutions.
 
 - `ord` Returns the Unicode code point for a given character. Example: `ord("A") == 65`
 - `chr` Returns the character for a given Unicode code point. Example: `chr(65) == "A"`
 - `len` Returns the length of the string. Example: `len("Hello") == 5`
+- `this.file` Returns a [`Path`](https://docs.python.org/3/library/pathlib.html#pure-paths) object that points to the current YAML file
+- `this.dir` Returns a `Path` that points to the current YAML folder
+
+#### Using `Path` expressions
+
+`Path` object supports the following properties:
+
+- `.parent`: Returns a new `Path` to the parent folder
+- `.name`: Returns the file or folder name.
+
+The `/` operator allows to append a platform-dependent folder separator.
+
+```yaml
+substitutions:
+  lib_name: mylib.h
+esphome:
+  includes:
+    - ${this.dir}/my_switch.h
+    - ${this.dir.parent / lib_name }
+```
+
+```yaml
+script:
+  - id: myscript
+    then:
+      - logger.log: "My script in ${this.file.name} launched!"
+      - logger.log: "Full path: ${this.file}"
+```
 
 {{< anchor "substitute-include-variables" >}}