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>

64 files changed, 7606 insertions, 0 deletions

diff --git a/docs/wiki/Application-Issues.md b/docs/wiki/Application-Issues.md
new file mode 100644
index 00000000..c02a820b
--- /dev/null
+++ b/docs/wiki/Application-Issues.md
@@ -0,0 +1,90 @@
+### Electron applications
+
+Electron-based applications can run directly on Wayland, but it's not the default.
+
+For Electron > 28, you can set an environment variable:
+```kdl
+environment {
+    ELECTRON_OZONE_PLATFORM_HINT "auto"
+}
+```
+
+For previous versions, you need to pass command-line flags to the target application:
+```
+--enable-features=UseOzonePlatform --ozone-platform-hint=auto
+```
+
+If the application has a [desktop entry](https://specifications.freedesktop.org/menu-spec/latest/menu-add-example.html), you can put the command-line arguments into the `Exec` section.
+
+### VSCode
+
+If you're having issues with some VSCode hotkeys, try starting `Xwayland` and setting the `DISPLAY=:0` environment variable for VSCode.
+That is, still running VSCode with the Wayland backend, but with `DISPLAY` set to a running Xwayland instance.
+Apparently, VSCode currently unconditionally queries the X server for a keymap.
+
+### WezTerm
+
+> [!NOTE]
+> Both of these issues seem to be fixed in the nightly build of WezTerm.
+
+There's [a bug](https://github.com/wezterm/wezterm/issues/4708) in WezTerm that it waits for a zero-sized Wayland configure event, so its window never shows up in niri. To work around it, put this window rule in the niri config (included in the default config):
+
+```kdl
+window-rule {
+    match app-id=r#"^org\.wezfurlong\.wezterm$"#
+    default-column-width {}
+}
+```
+
+This empty default column width lets WezTerm pick its own initial width which makes it show up properly.
+
+There's [another bug](https://github.com/wezterm/wezterm/issues/6472) in WezTerm that causes it to choose a wrong size when it's in a tiled state, and prevent resizing it.
+Niri puts windows in the tiled state with [`prefer-no-csd`](./Configuration:-Miscellaneous.md#prefer-no-csd).
+So if you hit this problem, comment out `prefer-no-csd` in the niri config and restart WezTerm.
+
+### Ghidra
+
+Some Java apps like Ghidra can show up blank under xwayland-satellite.
+To fix this, run them with the `_JAVA_AWT_WM_NONREPARENTING=1` environment variable.
+
+### rofi-wayland
+
+There's a bug in rofi-wayland that prevents it from accepting keyboard input on niri with errors in the output.
+It's been fixed in rofi, but [the fix had not been released yet](https://github.com/davatorium/rofi/discussions/2008).
+
+### Fullscreen games
+
+Some video games, both Linux-native and on Wine, have various issues when using non-stacking desktop environments.
+Most of these can be avoided with Valve's [gamescope](https://github.com/ValveSoftware/gamescope), for example:
+
+```sh
+gamescope -f -w 1920 -h 1080 -W 1920 -H 1080 --force-grab-cursor --backend sdl -- <game>
+```
+
+This command will run *<game>* in 1080p fullscreen—make sure to replace the width and height values to match your desired resolution.
+`--force-grab-cursor` forces gamescope to use relative mouse movement which prevents the cursor from escaping the game's window on multi-monitor setups.
+Note that `--backend sdl` is currently also required as gamescope's default Wayland backend doesn't lock the cursor properly (possibly related to https://github.com/ValveSoftware/gamescope/issues/1711).
+
+Steam users should use gamescope through a game's [launch options](https://help.steampowered.com/en/faqs/view/7D01-D2DD-D75E-2955) by replacing the game executable with `%command%`.
+Other game launchers such as [Lutris](https://lutris.net/) have their own ways of setting gamescope options.
+
+Running X11-based games with this method doesn't require Xwayland as gamescope creates its own Xwayland server.
+You can run Wayland-native games as well by passing `--expose-wayland` to gamescope, therefore eliminating X11 from the equation.
+
+### Steam
+
+On some systems, Steam will show a fully black window.
+To fix this, navigate to Settings -> Interface (via Steam's tray icon, or by blindly finding the Steam menu at the top left of the window), then **disable** GPU accelerated rendering in web views.
+Restart Steam and it should now work fine.
+
+If you do not want to disable GPU accelerated rendering you can instead try to pass the launch argument `-system-composer` instead.
+
+Steam notifications don't run through the standard notification daemon and show up as floating windows in the center of the screen.
+You can move them to a more convenient location by adding a window rule in your niri config:
+
+```kdl
+window-rule {
+    match app-id="steam" title=r#"^notificationtoasts_\d+_desktop$"#
+    default-floating-position x=10 y=10 relative-to="bottom-right"
+}
+```
diff --git a/docs/wiki/Configuration:-Animations.md b/docs/wiki/Configuration:-Animations.md
new file mode 100644
index 00000000..2400f568
--- /dev/null
+++ b/docs/wiki/Configuration:-Animations.md
@@ -0,0 +1,412 @@
+### Overview
+
+Niri has several animations which you can configure in the same way.
+Additionally, you can disable or slow down all animations at once.
+
+Here's a quick glance at the available animations with their default values.
+
+```kdl
+animations {
+    // Uncomment to turn off all animations.
+    // You can also put "off" into each individual animation to disable it.
+    // off
+
+    // Slow down all animations by this factor. Values below 1 speed them up instead.
+    // slowdown 3.0
+
+    // Individual animations.
+
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
+    }
+
+    window-close {
+        duration-ms 150
+        curve "ease-out-quad"
+    }
+
+    horizontal-view-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
+    window-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
+    window-resize {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
+    config-notification-open-close {
+        spring damping-ratio=0.6 stiffness=1000 epsilon=0.001
+    }
+
+    screenshot-ui-open {
+        duration-ms 200
+        curve "ease-out-quad"
+    }
+
+    overview-open-close {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+### Animation Types
+
+There are two animation types: easing and spring.
+Each animation can be either an easing or a spring.
+
+#### Easing
+
+This is a relatively common animation type that changes the value over a set duration using an interpolation curve.
+
+To use this animation, set the following parameters:
+
+- `duration-ms`: duration of the animation in milliseconds.
+- `curve`: the easing curve to use.
+
+```kdl
+animations {
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
+    }
+}
+```
+
+Currently, niri only supports four curves:
+
+- `ease-out-quad` <sup>Since: 0.1.5</sup>
+- `ease-out-cubic`
+- `ease-out-expo`
+- `linear` <sup>Since: 0.1.6</sup>
+
+You can get a feel for them on pages like [easings.net](https://easings.net/).
+
+#### Spring
+
+Spring animations use a model of a physical spring to animate the value.
+They notably feel better with touchpad gestures, because they take into account the velocity of your fingers as you release the swipe.
+Springs can also oscillate / bounce at the end with the right parameters if you like that sort of thing, but they don't have to (and by default they mostly don't).
+
+Due to springs using a physical model, the animation parameters are less obvious and generally should be tuned with trial and error.
+Notably, you cannot directly set the duration.
+You can use the [Elastic](https://flathub.org/apps/app.drey.Elastic) app to help visualize how the spring parameters change the animation.
+
+A spring animation is configured like this, with three mandatory parameters:
+
+```kdl
+animations {
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+}
+```
+
+The `damping-ratio` goes from 0.1 to 10.0 and has the following properties:
+
+- below 1.0: underdamped spring, will oscillate in the end.
+- above 1.0: overdamped spring, won't oscillate.
+- 1.0: critically damped spring, comes to rest in minimum possible time without oscillations.
+
+However, even with damping ratio = 1.0, the spring animation may oscillate if "launched" with enough velocity from a touchpad swipe.
+
+> [!WARNING]
+> Overdamped springs currently have some numerical stability issues and may cause graphical glitches.
+> Therefore, setting `damping-ratio` above `1.0` is not recommended.
+
+Lower `stiffness` will result in a slower animation more prone to oscillation.
+
+Set `epsilon` to a lower value if the animation "jumps" at the end.
+
+> [!TIP]
+> The spring *mass* (which you can see in Elastic) is hardcoded to 1.0 and cannot be changed.
+> Instead, change `stiffness` proportionally.
+> E.g. increasing mass by 2× is the same as decreasing stiffness by 2×.
+
+### Animations
+
+Now let's go into more detail on the animations that you can configure.
+
+#### `workspace-switch`
+
+Animation when switching workspaces up and down, including after the vertical touchpad gesture (a spring is recommended).
+
+```kdl
+animations {
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+}
+```
+
+#### `window-open`
+
+Window opening animation.
+
+This one uses an easing type by default.
+
+```kdl
+animations {
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
+    }
+}
+```
+
+##### `custom-shader`
+
+<sup>Since: 0.1.6</sup>
+
+You can write a custom shader for drawing the window during an open animation.
+
+See [this example shader](./examples/open_custom_shader.frag) for a full documentation with several animations to experiment with.
+
+If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader.
+When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri`
+
+> [!WARNING]
+>
+> Custom shaders do not have a backwards compatibility guarantee.
+> I may need to change their interface as I'm developing new features.
+
+Example: open will fill the current geometry with a solid gradient that gradually fades in.
+
+```kdl
+animations {
+    window-open {
+        duration-ms 250
+        curve "linear"
+
+        custom-shader r"
+            vec4 open_color(vec3 coords_geo, vec3 size_geo) {
+                vec4 color = vec4(0.0);
+
+                if (0.0 <= coords_geo.x && coords_geo.x <= 1.0
+                        && 0.0 <= coords_geo.y && coords_geo.y <= 1.0)
+                {
+                    vec4 from = vec4(1.0, 0.0, 0.0, 1.0);
+                    vec4 to = vec4(0.0, 1.0, 0.0, 1.0);
+                    color = mix(from, to, coords_geo.y);
+                }
+
+                return color * niri_clamped_progress;
+            }
+        "
+    }
+}
+```
+
+#### `window-close`
+
+<sup>Since: 0.1.5</sup>
+
+Window closing animation.
+
+This one uses an easing type by default.
+
+```kdl
+animations {
+    window-close {
+        duration-ms 150
+        curve "ease-out-quad"
+    }
+}
+```
+
+##### `custom-shader`
+
+<sup>Since: 0.1.6</sup>
+
+You can write a custom shader for drawing the window during a close animation.
+
+See [this example shader](./examples/close_custom_shader.frag) for a full documentation with several animations to experiment with.
+
+If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader.
+When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri`
+
+> [!WARNING]
+>
+> Custom shaders do not have a backwards compatibility guarantee.
+> I may need to change their interface as I'm developing new features.
+
+Example: close will fill the current geometry with a solid gradient that gradually fades away.
+
+```kdl
+animations {
+    window-close {
+        custom-shader r"
+            vec4 close_color(vec3 coords_geo, vec3 size_geo) {
+                vec4 color = vec4(0.0);
+
+                if (0.0 <= coords_geo.x && coords_geo.x <= 1.0
+                        && 0.0 <= coords_geo.y && coords_geo.y <= 1.0)
+                {
+                    vec4 from = vec4(1.0, 0.0, 0.0, 1.0);
+                    vec4 to = vec4(0.0, 1.0, 0.0, 1.0);
+                    color = mix(from, to, coords_geo.y);
+                }
+
+                return color * (1.0 - niri_clamped_progress);
+            }
+        "
+    }
+}
+```
+
+#### `horizontal-view-movement`
+
+All horizontal camera view movement animations, such as:
+
+- When a window off-screen is focused and the camera scrolls to it.
+- When a new window appears off-screen and the camera scrolls to it.
+- After a horizontal touchpad gesture (a spring is recommended).
+
+```kdl
+animations {
+    horizontal-view-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+#### `window-movement`
+
+<sup>Since: 0.1.5</sup>
+
+Movement of individual windows within a workspace.
+
+Includes:
+
+- Moving window columns with `move-column-left` and `move-column-right`.
+- Moving windows inside a column with `move-window-up` and `move-window-down`.
+- Moving windows out of the way upon window opening and closing.
+- Window movement between columns when consuming/expelling.
+
+This animation *does not* include the camera view movement, such as scrolling the workspace left and right.
+
+```kdl
+animations {
+    window-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+#### `window-resize`
+
+<sup>Since: 0.1.5</sup>
+
+Window resize animation.
+
+Only manual window resizes are animated, i.e. when you resize the window with `switch-preset-column-width` or `maximize-column`.
+Also, very small resizes (up to 10 pixels) are not animated.
+
+```kdl
+animations {
+    window-resize {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+##### `custom-shader`
+
+<sup>Since: 0.1.6</sup>
+
+You can write a custom shader for drawing the window during a resize animation.
+
+See [this example shader](./examples/resize_custom_shader.frag) for a full documentation with several animations to experiment with.
+
+If a custom shader fails to compile, niri will print a warning and fall back to the default, or previous successfully compiled shader.
+When running niri as a systemd service, you can see the warnings in the journal: `journalctl -ef /usr/bin/niri`
+
+> [!WARNING]
+>
+> Custom shaders do not have a backwards compatibility guarantee.
+> I may need to change their interface as I'm developing new features.
+
+Example: resize will show the next (after resize) window texture right away, stretched to the current geometry.
+
+```kdl
+animations {
+    window-resize {
+        custom-shader r"
+            vec4 resize_color(vec3 coords_curr_geo, vec3 size_curr_geo) {
+                vec3 coords_tex_next = niri_geo_to_tex_next * coords_curr_geo;
+                vec4 color = texture2D(niri_tex_next, coords_tex_next.st);
+                return color;
+            }
+        "
+    }
+}
+```
+
+#### `config-notification-open-close`
+
+The open/close animation of the config parse error and new default config notifications.
+
+This one uses an underdamped spring by default (`damping-ratio=0.6`) which causes a slight oscillation in the end.
+
+```kdl
+animations {
+    config-notification-open-close {
+        spring damping-ratio=0.6 stiffness=1000 epsilon=0.001
+    }
+}
+```
+
+#### `screenshot-ui-open`
+
+<sup>Since: 0.1.8</sup>
+
+The open (fade-in) animation of the screenshot UI.
+
+```kdl
+animations {
+    screenshot-ui-open {
+        duration-ms 200
+        curve "ease-out-quad"
+    }
+}
+```
+
+#### `overview-open-close`
+
+<sup>Since: 25.05</sup>
+
+The open/close zoom animation of the [Overview](./Overview.md).
+
+```kdl
+animations {
+    overview-open-close {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+### Synchronized Animations
+
+<sup>Since: 0.1.5</sup>
+
+Sometimes, when two animations are meant to play together synchronized, niri will drive them both with the same configuration.
+
+For example, if a window resize causes the view to move, then that view movement animation will also use the `window-resize` configuration (rather than the `horizontal-view-movement` configuration).
+This is especially important for animated resizes to look good when using `center-focused-column "always"`.
+
+As another example, resizing a window in a column vertically causes other windows to move up or down into their new position.
+This movement will use the `window-resize` configuration, rather than the `window-movement` configuration, to keep the animations synchronized.
+
+A few actions are still missing this synchronization logic, since in some cases it is difficult to implement properly.
+Therefore, for the best results, consider using the same parameters for related animations (they are all the same by default):
+
+- `horizontal-view-movement`
+- `window-movement`
+- `window-resize`
diff --git a/docs/wiki/Configuration:-Debug-Options.md b/docs/wiki/Configuration:-Debug-Options.md
new file mode 100644
index 00000000..f2d38de0
--- /dev/null
+++ b/docs/wiki/Configuration:-Debug-Options.md
@@ -0,0 +1,353 @@
+### Overview
+
+Niri has several options that are only useful for debugging, or are experimental and have known issues.
+They are not meant for normal use.
+
+> [!CAUTION]
+> These options are **not** covered by the [config breaking change policy](./Configuration:-Introduction.md#breaking-change-policy).
+> They can change or stop working at any point with little notice.
+
+Here are all the options at a glance:
+
+```kdl
+debug {
+    preview-render "screencast"
+    // preview-render "screen-capture"
+    enable-overlay-planes
+    disable-cursor-plane
+    disable-direct-scanout
+    restrict-primary-scanout-to-matching-format
+    render-drm-device "/dev/dri/renderD129"
+    for