github wiki replacement / mkdocs-docs (#2147)

* Add wiki based on mkdocs

* wording fixes

* fix github bg color on narrow

* Fix left sidebar section headers being bigger than pages

* fix hover accent

* fix list rendering on fractional layout

* fix videos

* fix automatic full links

* remove redundant commented css

* improve dark mode contrast

* update pygments for better child node coloring

* update logo

* remove blank lines

* add systemd language hint

---------

Co-authored-by: Ivan Molodetskikh <yalterz@gmail.com>

1 files changed, 379 insertions, 0 deletions

diff --git a/docs/wiki/Configuration:-Input.md b/docs/wiki/Configuration:-Input.md
new file mode 100644
index 00000000..c9ca0ba2
--- /dev/null
+++ b/docs/wiki/Configuration:-Input.md
@@ -0,0 +1,379 @@
+### Overview
+
+In this section you can configure input devices like keyboard and mouse, and some input-related options.
+
+There's a section for each device type: `keyboard`, `touchpad`, `mouse`, `trackpoint`, `tablet`, `touch`.
+Settings in those sections will apply to every device of that type.
+Currently, there's no way to configure specific devices individually (but that is planned).
+
+All settings at a glance:
+
+```kdl
+input {
+    keyboard {
+        xkb {
+            // layout "us"
+            // variant "colemak_dh_ortho"
+            // options "compose:ralt,ctrl:nocaps"
+            // model ""
+            // rules ""
+            // file "~/.config/keymap.xkb"
+        }
+
+        // repeat-delay 600
+        // repeat-rate 25
+        // track-layout "global"
+        numlock
+    }
+
+    touchpad {
+        // off
+        tap
+        // dwt
+        // dwtp
+        // drag false
+        // drag-lock
+        natural-scroll
+        // accel-speed 0.2
+        // accel-profile "flat"
+        // scroll-factor 1.0
+        // scroll-method "two-finger"
+        // scroll-button 273
+        // scroll-button-lock
+        // tap-button-map "left-middle-right"
+        // click-method "clickfinger"
+        // left-handed
+        // disabled-on-external-mouse
+        // middle-emulation
+    }
+
+    mouse {
+        // off
+        // natural-scroll
+        // accel-speed 0.2
+        // accel-profile "flat"
+        // scroll-factor 1.0
+        // scroll-method "no-scroll"
+        // scroll-button 273
+        // scroll-button-lock
+        // left-handed
+        // middle-emulation
+    }
+
+    trackpoint {
+        // off
+        // natural-scroll
+        // accel-speed 0.2
+        // accel-profile "flat"
+        // scroll-method "on-button-down"
+        // scroll-button 273
+        // scroll-button-lock
+        // left-handed
+        // middle-emulation
+    }
+
+    trackball {
+        // off
+        // natural-scroll
+        // accel-speed 0.2
+        // accel-profile "flat"
+        // scroll-method "on-button-down"
+        // scroll-button 273
+        // scroll-button-lock
+        // left-handed
+        // middle-emulation
+    }
+
+    tablet {
+        // off
+        map-to-output "eDP-1"
+        // left-handed
+        // calibration-matrix 1.0 0.0 0.0 0.0 1.0 0.0
+    }
+
+    touch {
+        // off
+        map-to-output "eDP-1"
+    }
+
+    // disable-power-key-handling
+    // warp-mouse-to-focus
+    // focus-follows-mouse max-scroll-amount="0%"
+    // workspace-auto-back-and-forth
+
+    // mod-key "Super"
+    // mod-key-nested "Alt"
+}
+```
+
+### Keyboard
+
+#### Layout
+
+In the `xkb` section, you can set layout, variant, options, model and rules.
+These are passed directly to libxkbcommon, which is also used by most other Wayland compositors.
+See the `xkeyboard-config(7)` manual for more information.
+
+```kdl
+input {
+    keyboard {
+        xkb {
+            layout "us"
+            variant "colemak_dh_ortho"
+            options "compose:ralt,ctrl:nocaps"
+        }
+    }
+}
+```
+
+> [!TIP]
+>
+> <sup>Since: 25.02</sup>
+>
+> Alternatively, you can directly set a path to a .xkb file containing an xkb keymap.
+> This overrides all other xkb settings.
+>
+> ```kdl
+> input {
+>     keyboard {
+>         xkb {
+>             file "~/.config/keymap.xkb"
+>         }
+>     }
+> }
+> ```
+
+> [!NOTE]
+>
+> <sup>Since: next release</sup>
+>
+> If the `xkb` section is empty (like it is by default), niri will fetch xkb settings from systemd-localed at `org.freedesktop.locale1` over D-Bus.
+> This way, for example, system installers can dynamically set the niri keyboard layout.
+> You can see this layout in `localectl` and change it with `localectl set-x11-keymap`, for example:
+>
+> ```sh
+> $ localectl set-x11-keymap "us" "" "colemak_dh_ortho" "compose:ralt,ctrl:nocaps"
+> $ localectl
+> System Locale: LANG=en_US.UTF-8
+>                LC_NUMERIC=ru_RU.UTF-8
+>                LC_TIME=ru_RU.UTF-8
+>                LC_MONETARY=ru_RU.UTF-8
+>                LC_PAPER=ru_RU.UTF-8
+>                LC_MEASUREMENT=ru_RU.UTF-8
+>     VC Keymap: us-colemak_dh_ortho
+>    X11 Layout: us
+>   X11 Variant: colemak_dh_ortho
+>   X11 Options: compose:ralt,ctrl:nocaps
+> ```
+>
+> By default, `localectl` will set the TTY keymap to the closest match of the XKB keymap.
+> You can prevent that with a `--no-convert` flag, for example: `localectl set-x11-keymap --no-convert "us,ru"`.
+>
+> These settings are picked up by some other programs too, like GDM.
+
+When using multiple layouts, niri can remember the current layout globally (the default) or per-window.
+You can control this with the `track-layout` option.
+
+- `global`: layout change is global for all windows.
+- `window`: layout is tracked for each window individually.
+
+```kdl
+input {
+    keyboard {
+        track-layout "global"
+    }
+}
+```
+
+#### Repeat
+
+Delay is in milliseconds before the keyboard repeat starts.
+Rate is in characters per second.
+
+```kdl
+input {
+    keyboard {
+        repeat-delay 600
+        repeat-rate 25
+    }
+}
+```
+
+#### Num Lock
+
+<sup>Since: 25.05</sup>
+
+Set the `numlock` flag to turn on Num Lock automatically at startup.
+
+You might want to disable (comment out) `numlock` if you're using a laptop with a keyboard that overlays Num Lock keys on top of regular keys.
+
+```kdl
+input {
+    keyboard {
+        numlock
+    }
+}
+```
+
+### Pointing Devices
+
+Most settings for the pointing devices are passed directly to libinput.
+Other Wayland compositors also use libinput, so it's likely you will find the same settings there.
+For flags like `tap`, omit them or comment them out to disable the setting.
+
+A few settings are common between input devices:
+
+- `off`: if set, no events will be sent from this device.
+
+A few settings are common between `touchpad`, `mouse`, `trackpoint`, and `trackball`:
+
+- `natural-scroll`: if set, inverts the scrolling direction.
+- `accel-speed`: pointer acceleration speed, valid values are from `-1.0` to `1.0` where the default is `0.0`.
+- `accel-profile`: can be `adaptive` (the default) or `flat` (disables pointer acceleration).
+- `scroll-method`: when to generate scroll events instead of pointer motion events, can be `no-scroll`, `two-finger`, `edge`, or `on-button-down`.
+  The default and supported methods vary depending on the device type.
+- `scroll-button`: <sup>Since: 0.1.10</sup> the button code used for the `on-button-down` scroll method. You can find it in `libinput debug-events`.
+- `scroll-button-lock`: <sup>Since: next release</sup> when enabled, the button does not need to be held down. Pressing once engages scrolling, pressing a second time disengages it, and double click acts as single click of the the underlying button.
+- `left-handed`: if set, changes the device to left-handed mode.
+- `middle-emulation`: emulate a middle mouse click by pressing left and right mouse buttons at once.
+
+Settings specific to `touchpad`s:
+
+- `tap`: tap-to-click.
+- `dwt`: disable-when-typing.
+- `dwtp`: disable-when-trackpointing.
+- `drag`: <sup>Since: 25.05</sup> can be `true` or `false`, controls if tap-and-drag is enabled.
+- `drag-lock`: <sup>Since: 25.02</sup> if set, lifting the finger off for a short time while dragging will not drop the dragged item. See the [libinput documentation](https://wayland.freedesktop.org/libinput/doc/latest/tapping.html#tap-and-drag).
+- `tap-button-map`: can be `left-right-middle` or `left-middle-right`, controls which button corresponds to a two-finger tap and a three-finger tap.
+- `click-method`: can be `button-areas` or `clickfinger`, changes the [click method](https://wayland.freedesktop.org/libinput/doc/latest/clickpad-softbuttons.html).
+- `disabled-on-external-mouse`: do not send events while external pointer device is plugged in.
+
+Settings specific to `touchpad` and `mouse`:
+
+- `scroll-factor`: <sup>Since: 0.1.10</sup> scales the scrolling speed by this value.
+
+Settings specific to `tablet`s:
+
+- `calibration-matrix`: <sup>Since: 25.02</sup> set to six floating point numbers to change the calibration matrix. See the [`LIBINPUT_CALIBRATION_MATRIX` documentation](https://wayland.freedesktop.org/libinput/doc/latest/device-configuration-via-udev.html) for examples.
+
+Tablets and touchscreens are absolute pointing devices that can be mapped to a specific output like so:
+
+```kdl
+input {
+    tablet {
+        map-to-output "eDP-1"
+    }
+
+    touch {
+        map-to-output "eDP-1"
+    }
+}
+```
+
+Valid output names are the same as the ones used for output configuration.
+
+<sup>Since: 0.1.7</sup> When a tablet is not mapped to any output, it will map to the union of all connected outputs, without aspect ratio correction.
+
+### General Settings
+
+These settings are not specific to a particular input device.
+
+#### `disable-power-key-handling`
+
+By default, niri will take over the power button to make it sleep instead of power off.
+Set this if you would like to configure the power button elsewhere (i.e. `logind.conf`).
+
+```kdl
+input {
+    disable-power-key-handling
+}
+```
+
+#### `warp-mouse-to-focus`
+
+Makes the mouse warp to newly focused windows.
+
+Does not make the cursor visible if it had been hidden.
+
+```kdl
+input {
+    warp-mouse-to-focus
+}
+```
+
+By default, the cursor warps *separately* horizontally and vertically.
+I.e. if moving the mouse only horizontally is enough to put it inside the newly focused window, then the mouse will move only horizontally, and not vertically.
+
+<sup>Since: 25.05</sup> You can customize this with the `mode` property.
+
+- `mode="center-xy"`: warps by both X and Y coordinates together.
+So if the mouse was anywhere outside the newly focused window, it will warp to the center of the window.
+- `mode="center-xy-always"`: warps by both X and Y coordinates together, even if the mouse was already somewhere inside the newly focused window.
+
+```kdl
+input {
+    warp-mouse-to-focus mode="center-xy"
+}
+```
+
+#### `focus-follows-mouse`
+
+Focuses windows and outputs automatically when moving the mouse over them.
+
+```kdl
+input {
+    focus-follows-mouse
+}
+```
+
+<sup>Since: 0.1.8</sup> You can optionally set `max-scroll-amount`.
+Then, focus-follows-mouse won't focus a window if it will result in the view scrolling more than the set amount.
+The value is a percentage of the working area width.
+
+```kdl
+input {
+    // Allow focus-follows-mouse when it results in scrolling at most 10% of the screen.
+    focus-follows-mouse max-scroll-amount="10%"
+}
+```
+
+```kdl
+input {
+    // Allow focus-follows-mouse only when it will not scroll the view.
+    focus-follows-mouse max-scroll-amount="0%"
+}
+```
+
+#### `workspace-auto-back-and-forth`
+
+Normally, switching to the same workspace by index twice will do nothing (since you're already on that workspace).
+If this flag is enabled, switching to the same workspace by index twice will switch back to the previous workspace.
+
+Niri will correctly switch to the workspace you came from, even if workspaces were reordered in the meantime.
+
+```kdl
+input {
+    workspace-auto-back-and-forth
+}
+```
+
+#### `mod-key`, `mod-key-nested`
+
+<sup>Since: 25.05</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"
+}
+```