From c621307577aabf7da065d6a756213f4b4d6c3d03 Mon Sep 17 00:00:00 2001
From: Rolo <roloedits@gmail.com>
Date: Sun, 30 Mar 2025 23:10:01 -0700
Subject: [PATCH] feat(docs): add documentation for custom commands

---
 book/src/SUMMARY.md         |   1 +
 book/src/custom-commands.md | 105 ++++++++++++++++++++++++++++++++++++
 book/src/remapping.md       |   4 --
 3 files changed, 106 insertions(+), 4 deletions(-)
 create mode 100644 book/src/custom-commands.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 82715b7ef..be2f17607 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -22,6 +22,7 @@
   - [Editor](./editor.md)
   - [Themes](./themes.md)
   - [Key remapping](./remapping.md)
+  - [Custom commands](./custom-commands.md)
   - [Languages](./languages.md)
 - [Guides](./guides/README.md)
   - [Adding languages](./guides/adding_languages.md)
diff --git a/book/src/custom-commands.md b/book/src/custom-commands.md
new file mode 100644
index 000000000..ca6c8c34e
--- /dev/null
+++ b/book/src/custom-commands.md
@@ -0,0 +1,105 @@
+# Custom Commands
+
+There are three kinds of commands that can be used in custom commands:
+
+* Static commands: commands like `move_char_right` which are usually bound to
+  keys and used for movement and editing. A list of static commands is
+  available in the [Keymap](./keymap.html) documentation and in the source code
+  in [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs)
+  at the invocation of `static_commands!` macro.
+* Typable commands: commands that can be executed from command mode (`:`), for
+  example `:write!`. See the [Commands](./commands.html) documentation for a
+  list of available typeable commands or the `TypableCommandList` declaration in
+  the source code at [`helix-term/src/commands/typed.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands/typed.rs).
+* Macros: sequences of keys that are executed in order. These keybindings
+  start with `@` and then list any number of keys to be executed. For example
+  `@miw` can be used to select the surrounding word. For now, macro keybindings
+  are not allowed in sequences due to limitations in the way that
+  command sequences are executed. Modifier keys (e.g. Alt+o) can be used
+  like `"<A-o>"`, e.g. `"@miw<A-o>"`
+
+To remap commands, create a `config.toml` file in your `helix` configuration
+directory (default `~/.config/helix` on Linux systems) with a structure like
+this:
+
+```toml
+[commands]
+":wcb" = [":write", ":buffer-close"] # Maps `:wcb` to write the current buffer and then close it
+":f" = ":format" # Maps `:f` to format the current buffer
+":W" = ":write!" # Maps `:W` to forcefully save the current buffer
+":Q" = ":quit!" # Maps `:Q` to forcefully quit helix
+":hints" = ":toggle lsp.display-inlay-hints" # Maps `:hints` to toggle inlay hints
+```
+
+## Shadowing Built-in Commands
+
+If you redefine a built-in command but still need access to the original, prefix the command with `^` when entering it.
+
+Example:
+
+```toml
+[commands]
+":w" = ":write!" # Force save
+```
+
+To invoke the original behavior:
+
+```
+:^w
+```
+
+This executes the original `:write` command instead of the remapped one.
+
+## Visibility
+
+By default, custom commands appear in the command list. If you prefer to keep them hidden, omit the `:` prefix:
+
+```toml
+[commands]
+"0" = ":goto 1" # `:0` moves to the first line
+```
+
+Even though `:0` can still be used, it won't appear in the command list.
+
+## Positional Arguments
+
+To pass arguments to an underlying command, use `%arg`:
+
+```toml
+[commands]
+":cc" = ":pipe xargs ccase --to %arg{0}"
+```
+
+Example usage:
+
+```
+:cc snake
+```
+
+This executes: `:pipe xargs ccase --to snake`.
+
+- `%arg` uses zero-based indexing (`%arg{0}`, `%arg{1}`, etc.).
+- Valid argument brace syntax follows the [Command Line](./command-line.html) conventions.
+
+## Descriptions and Prompts
+
+To provide descriptions for custom commands, use optional fields:
+
+```toml
+[commands.":wcd!"]
+commands = [":write! %arg(0)", ":cd %sh{ %arg(0) | path dirname }"]
+desc = "Force save buffer, then change directory"
+accepts = "<path>"
+```
+
+## Command Completion
+
+To enable autocompletion for a custom command, assign it an existing completer:
+
+```toml
+[commands.":touch"]
+commands = [":noop %sh{ touch %arg{0} }"]
+completer = ":write"
+```
+
+This allows `:touch` to inherit `:write`'s file path completion.
diff --git a/book/src/remapping.md b/book/src/remapping.md
index 23bb80c55..ea532030a 100644
--- a/book/src/remapping.md
+++ b/book/src/remapping.md
@@ -1,9 +1,5 @@
 ## Key remapping
 
-Helix currently supports one-way key remapping through a simple TOML configuration
-file. (More powerful solutions such as rebinding via commands will be
-available in the future).
-
 There are three kinds of commands that can be used in keymaps:
 
 * Static commands: commands like `move_char_right` which are usually bound to