From 61d7f68f9b7f32073cb989416fa9c0d2465199f3 Mon Sep 17 00:00:00 2001
From: Dmytro Maluka <dmitrymaluka@gmail.com>
Date: Sat, 5 Jul 2025 17:17:21 +0200
Subject: [PATCH] help: Document binding keys to lua functions

This is still not properly documented (except for the example in
tutorial.md), so document it.
---
 runtime/help/keybindings.md | 42 +++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/runtime/help/keybindings.md b/runtime/help/keybindings.md
index 15163f72..3817131d 100644
--- a/runtime/help/keybindings.md
+++ b/runtime/help/keybindings.md
@@ -105,6 +105,48 @@ Now when you press `Ctrl-g`, `help` will appear in the command bar and your
 cursor will be placed after it (note the space in the json that controls the
 cursor placement).
 
+## Binding Lua functions
+
+You can also bind a key to a Lua function provided by a plugin, or by your own
+`~/.config/micro/init.lua`. For example:
+
+```json
+{
+    "Alt-q": "lua:foo.bar"
+}
+```
+
+where `foo` is the name of the plugin and `bar` is the name of the lua function
+in it, e.g.:
+
+```lua
+local micro = import("micro")
+
+function bar(bp)
+    micro.InfoBar():Message("Bar action triggered")
+    return true
+end
+```
+
+See `> help plugins` for more informations on how to write lua functions.
+
+For `~/.config/micro/init.lua` the plugin name is `initlua` (so the keybinding
+in this example would be `"Alt-q": "lua:initlua.bar"`).
+
+The currently active bufpane is passed to the lua function as the argument. If
+the key is a mouse button, e.g. `MouseLeft` or `MouseWheelUp`, the mouse event
+info is passed to the lua function as the second argument, of type
+`*tcell.EventMouse`. See https://pkg.go.dev/github.com/micro-editor/tcell/v2#EventMouse
+for the description of this type and its methods.
+
+The return value of the lua function defines whether the action has succeeded.
+This is used when chaining lua functions with other actions. They can be chained
+the same way as regular actions as described above, for example:
+
+```
+"Alt-q": "lua:initlua.bar|Quit"
+```
+
 ## Binding raw escape sequences
 
 Only read this section if you are interested in binding keys that aren't on the