diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc
index 2a61e7f9..fe3e4a13 100644
--- a/doc/pages/expansions.asciidoc
+++ b/doc/pages/expansions.asciidoc
@@ -126,7 +126,11 @@ informations about Kakoune's state:
     (e.g. *$kak_client_env_SHELL* is the SHELL variable)
 
 Note that in order for Kakoune to pass a value in the environment, the
-variable has to be spelled out within the body of the expansion
+variable has to be spelled out within the body of the expansion.
+
+Those environment variables are available in every context where
+Kakoune use a shell command, such as the `|`, `!` or `$` normal
+mode commands (See <<keys#,`:doc keys`>>).
 
 == Markup strings
 
diff --git a/doc/pages/keys.asciidoc b/doc/pages/keys.asciidoc
index 1d4b74f3..e03eae39 100644
--- a/doc/pages/keys.asciidoc
+++ b/doc/pages/keys.asciidoc
@@ -298,17 +298,21 @@ is a sequence of non whitespace characters
 
 *|*::
     pipe each selection through the given external filter program and
-    replace the selection with its output
+    replace the selection with its output. Shell expansions are available,
+    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
 *<a-|>*::
     pipe each selection through the given external filter program and
-    ignore its output
+    ignore its output. Shell expansions are available,
+    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
 *!*::
-    insert command output before selection
+    insert command output before selection. Shell expansions are available,
+    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
 *<a-!>*::
-    append command output after selection
+    append command output after selection. Shell expansions are available,
+    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
 *u*::
     undo last change
@@ -542,7 +546,8 @@ to skim through the jump list using:
 
 *$*::
     pipe each selection to the given shell command and keep the ones
-    for which the shell returned 0
+    for which the shell returned 0. Shell expansions are available,
+    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
 
 == Object Selection