From 9530fab4b6f320d212f966e46a0353931a010471 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Delafargue?= <clement@delafargue.name>
Date: Tue, 17 Jan 2023 09:48:43 +0100
Subject: [PATCH] doc: expand documentation on configuring minor modes

Fixes #3835, #4811
---
 book/src/keymap.md    |  3 +++
 book/src/remapping.md | 27 +++++++++++++++++++++++++--
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/book/src/keymap.md b/book/src/keymap.md
index 924559114..0550e57f3 100644
--- a/book/src/keymap.md
+++ b/book/src/keymap.md
@@ -166,6 +166,9 @@ These sub-modes are accessible from normal mode and typically switch back to nor
 | `Ctrl-w` | Enter [window mode](#window-mode)                  | N/A            |
 | `Space`  | Enter [space mode](#space-mode)                    | N/A            |
 
+These modes (except command mode) can be configured by
+[remapping keys](https://docs.helix-editor.com/remapping.html#minor-modes).
+
 #### View mode
 
 Accessed by typing `z` in [normal mode](#normal-mode).
diff --git a/book/src/remapping.md b/book/src/remapping.md
index 2eac8846f..8339e05fc 100644
--- a/book/src/remapping.md
+++ b/book/src/remapping.md
@@ -25,8 +25,31 @@ j = { k = "normal_mode" } # Maps `jk` to exit insert mode
 ```
 > NOTE: Typable commands can also be remapped, remember to keep the `:` prefix to indicate it's a typable command.
 
-> NOTE: Bindings can be nested, to create (or edit) minor modes: `g = { a = "code_action"}` adds a new entry to
-> the `goto` mode.
+## Minor modes
+
+Minor modes are accessed by pressing a key (usually from normal mode), giving access to dedicated bindings. Bindings
+can be modified or added by nesting definitions.
+
+```toml
+[keys.insert.j]
+k = "normal_mode" # Maps `jk` to exit insert mode
+
+[keys.normal.g]
+a = "code_action" # Maps `ga` to show possible code actions
+
+# invert `j` and `k` in view mode
+[keys.normal.z]
+j = "scroll_up"
+k = "scroll_down"
+
+# create a new minor mode bound to `+`
+[keys.normal."+"]
+m = ":run-shell-command make"
+c = ":run-shell-command cargo build"
+t = ":run-shell-command cargo test"
+```
+
+## Special keys and modifiers
 
 Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes
 `C-`, `S-` and `A-`. Special keys are encoded as follows: