wiki: Document mod-key, mod-key-nested

2 files changed, 26 insertions, 0 deletions

diff --git a/wiki/Configuration:-Input.md b/wiki/Configuration:-Input.md
index 4fdfdf4f..9245583b 100644
--- a/wiki/Configuration:-Input.md
+++ b/wiki/Configuration:-Input.md
@@ -95,6 +95,9 @@ input {
     // warp-mouse-to-focus
     // focus-follows-mouse max-scroll-amount="0%"
     // workspace-auto-back-and-forth
+
+    // mod-key "Super"
+    // mod-key-nested "Alt"
 }
 ```
 
@@ -288,3 +291,24 @@ input {
     workspace-auto-back-and-forth
 }
 ```
+
+#### `mod-key`, `mod-key-nested`
+
+<sup>Since: next release</sup>
+
+Customize the `Mod` key for [key bindings](./Configuration:-Key-Bindings.md).
+Only valid modifiers are allowed, e.g. `Super`, `Alt`, `Mod3`, `Mod5`, `Ctrl`, `Shift`.
+
+By default, `Mod` is equal to `Super` when running niri on a TTY, and to `Alt` when running niri as a nested winit window.
+
+> [!NOTE]
+> There are a lot of default bindings with Mod, none of them "make it through" to the underlying window.
+> You probably don't want to set `mod-key` to Ctrl or Shift, since Ctrl is commonly used for app hotkeys, and Shift is used for, well, regular typing.
+
+```kdl
+// Switch the mod keys around: use Alt normally, and Super inside a nested window.
+input {
+    mod-key "Alt"
+    mod-key-nested "Super"
+}
+```
diff --git a/wiki/Configuration:-Key-Bindings.md b/wiki/Configuration:-Key-Bindings.md
index 11df52a2..5634bb5e 100644
--- a/wiki/Configuration:-Key-Bindings.md
+++ b/wiki/Configuration:-Key-Bindings.md
@@ -31,6 +31,8 @@ Valid modifiers are:
 This way, you can test niri in a window without causing too many conflicts with the host compositor's key bindings.
 For this reason, most of the default keys use the `Mod` modifier.
 
+<sup>Since: next release</sup> You can customize the `Mod` key [in the `input` section of the config](./Configuration:-Input.md#mod-key-mod-key-nested).
+
 > [!TIP]
 > To find an XKB name for a particular key, you may use a program like [`wev`](https://git.sr.ht/~sircmpwn/wev).
 >