diff --git a/doc/pages/mapping.asciidoc b/doc/pages/mapping.asciidoc
index c21bd90b..8e6699f7 100644
--- a/doc/pages/mapping.asciidoc
+++ b/doc/pages/mapping.asciidoc
@@ -53,6 +53,28 @@ set to the same sequence of keys passed using the *expected* argument.
 For more information about the values of the *scope* parameter, refer to
 <<scopes#,`:doc scopes`>>.
 
+== Mapping commands
+
+It's common to use a normal-mode or user-mode mapping to trigger a command,
+like this:
+
+----
+map global user n ': make-next-error<ret>'
+----
+
+Note the space between the `:` and the command. This prevents Kakoune from
+adding this command to the prompt history, so the user won't have to scroll
+past it to review commands they actually typed.
+
+If you make a normal-mode mapping, you can prefix it with a count or a register
+name like any other normal-mode key. You can forward this information to the
+command you invoke with the `%val{count}` and `%val{register}` expansions
+(See <<expansions#`:doc expansions`>>). For example:
+
+----
+map global normal = ': echo Got count %val{count} and reg %val{register}<ret>'
+----
+
 == Mappable keys
 
 See <<keys#,`:doc keys`>> to discover the list of default bindings.