diff --git a/docs/src/tasks.md b/docs/src/tasks.md
index b30b722007116d32435936205971419b5652689d..f2986c9951fe660efdc54e2bb984403cdb6da1cd 100644
--- a/docs/src/tasks.md
+++ b/docs/src/tasks.md
@@ -132,6 +132,27 @@ Or explicitly include escaped quotes like so:
 }
 ```
 
+### Task filtering based on variables
+
+Task definitions with variables which are not present at the moment the task list is determined are filtered out.
+For example, the following task will appear in the spawn modal only if there is a text selection:
+
+```json
+{
+  "label": "selected text",
+  "command": "echo \"$ZED_SELECTED_TEXT\""
+}
+```
+
+Set default values to such variables to have such tasks always displayed:
+
+```json
+{
+  "label": "selected text with default",
+  "command": "echo \"${ZED_SELECTED_TEXT:no text selected}\""
+}
+```
+
 ## Oneshot tasks
 
 The same task modal opened via `task: spawn` supports arbitrary bash-like command execution: type a command inside the modal text field, and use `opt-enter` to spawn it.