From 70acff6cd0652942ceb614df098a2e1572abc1ae Mon Sep 17 00:00:00 2001
From: Javier Peletier <jm@epiclabs.io>
Date: Wed, 29 Oct 2025 17:20:34 +0100
Subject: [PATCH] doc conditional packages

---
 content/components/packages.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/content/components/packages.md b/content/components/packages.md
index 20af5a6aa3..fc7d5f7903 100644
--- a/content/components/packages.md
+++ b/content/components/packages.md
@@ -166,6 +166,28 @@ switch:
     # ...
 ```
 
+{{< anchor "config-packages_conditional" >}}
+
+## Conditionally including a package
+
+You can include a package based on a condition, or choose a package dinamically by loading your package with `!include` into a substitution variable instead of under `packages`:
+
+```yaml
+# In config.yaml
+substitutions:
+  left_garage_door: !include
+    file: garage-door.yaml
+    vars:
+      door_name: Left
+
+  enable_extra_door: true
+
+packages:
+  extra_door: ${ left_garage_door if enable_extra_door else {} }
+```
+
+The above utilizes a {{< docref "/components/substitutions#jinja-expressions" "Jinja expression" >}} to determine whether `left_garage_door` package is actually included. `enable_extra_door` can be set from the {{< docref "/components/substitutions#command-line-substitutions" "command line" >}} as well.
+
 {{< anchor "config-packages_extend" >}}
 
 ## Extend