wiki: update wiki kdl snippets

Signed-off-by: Suyashtnt <suyashtnt@gmail.com>
2026-06-24 02:01:18 +07:00 · 2024-07-08 15:14:01 +02:00
parent f2290a43d9
commit 3be6e38af3
11 changed files with 138 additions and 149 deletions
@@ -20,7 +20,7 @@ Both of these can be fixed by resizing the new Chromium window.
 There's [a bug](https://github.com/wez/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 {}
@@ -5,7 +5,7 @@ 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.
@@ -67,7 +67,7 @@ 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
@@ -97,7 +97,7 @@ You can use the [Elastic](https://flathub.org/apps/app.drey.Elastic) app to help
 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
@@ -134,7 +134,7 @@ Now let's go into more detail on the animations that you can configure.
 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
@@ -148,7 +148,7 @@ Window opening animation.
 This one uses an easing type by default.
-```
+```kdl
 animations {
    window-open {
        duration-ms 150
@@ -175,7 +175,7 @@ When running niri as a systemd service, you can see the warnings in the journal:
 Example: open will fill the current geometry with a solid gradient that gradually fades in.
-```
+```kdl
 animations {
    window-open {
        duration-ms 250
@@ -208,7 +208,7 @@ Window closing animation.
 This one uses an easing type by default.
-```
+```kdl
 animations {
    window-close {
        duration-ms 150
@@ -235,7 +235,7 @@ When running niri as a systemd service, you can see the warnings in the journal:
 Example: close will fill the current geometry with a solid gradient that gradually fades away.
-```
+```kdl
 animations {
    window-close {
        custom-shader r"
@@ -265,7 +265,7 @@ All horizontal camera view movement animations, such as:
 - 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
@@ -288,7 +288,7 @@ Includes:
 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
@@ -305,7 +305,7 @@ 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
@@ -331,7 +331,7 @@ When running niri as a systemd service, you can see the warnings in the journal:
 Example: resize will show the next (after resize) window texture right away, stretched to the current geometry.
-```
+```kdl
 animations {
    window-resize {
        custom-shader r"
@@ -351,7 +351,7 @@ The open/close animation of the config parse error and new default config notifi
 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
@@ -365,7 +365,7 @@ animations {
 The open (fade-in) animation of the screenshot UI.
-```
+```kdl
 animations {
    screenshot-ui-open {
        duration-ms 200
@@ -9,7 +9,7 @@ They are not meant for normal use.
 Here are all the options at a glance:
-```
+```kdl
 debug {
    preview-render "screencast"
    // preview-render "screen-capture"
@@ -20,7 +20,6 @@ debug {
    dbus-interfaces-in-non-session-instances
    wait-for-frame-completion-before-queueing
    emulate-zero-presentation-time
    enable-color-transformations-capability
 }
 binds {
@@ -36,7 +35,7 @@ Make niri render the monitors the same way as for a screencast or a screen captu
 Useful for previewing the `block-out-from` window rule.
-```
+```kdl
 debug {
    preview-render "screencast"
    // preview-render "screen-capture"
@@ -50,7 +49,7 @@ May cause frame drops during some animations on some hardware (which is why it i
 Direct scanout into the primary plane is always enabled.
-```
+```kdl
 debug {
    enable-overlay-planes
 }
@@ -63,7 +62,7 @@ The cursor will be rendered together with the rest of the frame.
 Useful to work around driver bugs on specific hardware.
-```
+```kdl
 debug {
    disable-cursor-plane
 }
@@ -73,7 +72,7 @@ debug {
 Disable direct scanout to both the primary plane and the overlay planes.
-```
+```kdl
 debug {
    disable-direct-scanout
 }
@@ -85,7 +84,7 @@ Override the DRM device that niri will use for all rendering.
 You can set this to make niri use a different primary GPU than the default one.
-```
+```kdl
 debug {
    render-drm-device "/dev/dri/renderD129"
 }
@@ -99,7 +98,7 @@ Useful for testing screencasting changes without having to relogin.
 The main niri instance will *not* currently take back the interfaces when you close the test instance, so you will need to relogin in the end to make screencasting work again.
-```
+```kdl
 debug {
    dbus-interfaces-in-non-session-instances
 }
@@ -111,7 +110,7 @@ Wait until every frame is done rendering before handing it over to DRM.
 Useful for diagnosing certain synchronization and performance problems.
-```
+```kdl
 debug {
    wait-for-frame-completion-before-queueing
 }
@@ -123,26 +122,12 @@ Emulate zero (unknown) presentation time returned from DRM.
 This is a thing on NVIDIA proprietary drivers, so this flag can be used to test that niri doesn't break too hard on those systems.
-```
+```kdl
 debug {
    emulate-zero-presentation-time
 }
 ```
 ### `enable-color-transformations-capability`
 Enable the color-transformations capability of the Smithay renderer.
 May cause a slight decrease in rendering performance.
 Currently, should cause no visible changes in behavior, but it will be needed for HDR support whenever that happens.
 So, this flag exists to be able to make sure that nothing breaks.
 ```
 debug {
    enable-color-transformations-capability
 }
 ```
 ### Key Bindings
 These are not debug options, but rather key bindings.
@@ -153,7 +138,7 @@ Tints all surfaces green, unless they are being directly scanned out.
 Useful to check if direct scanout is working.
-```
+```kdl
 binds {
    Mod+Shift+Ctrl+T { toggle-debug-tint; }
 }
@@ -167,7 +152,7 @@ Tints regions marked as opaque with blue and the rest of the render elements wit
 Useful to check how Wayland surfaces and internal render elements mark their parts as opaque, which is a rendering performance optimization.
-```
+```kdl
 binds {
    Mod+Shift+Ctrl+O { debug-toggle-opaque-regions; }
 }
@@ -179,7 +164,7 @@ binds {
 Tints damaged regions with red.
-```
+```kdl
 binds {
    Mod+Shift+Ctrl+D { debug-toggle-damage; }
 }
@@ -8,7 +8,7 @@ Currently, there's no way to configure specific devices individually (but that i
 All settings at a glance:
-```
+```kdl
 input {
    keyboard {
        xkb {
@@ -81,7 +81,7 @@ 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 {
@@ -99,7 +99,7 @@ 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"
@@ -112,7 +112,7 @@ input {
 Delay is in milliseconds before the keyboard repeat starts.
 Rate is in characters per second.
-```
+```kdl
 input {
    keyboard {
        repeat-delay 600
@@ -154,7 +154,7 @@ Settings specific to `touchpad`, `mouse` and `tablet`:
 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"
@@ -179,7 +179,7 @@ These settings are not specific to a particular input device.
 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
 }
@@ -191,7 +191,7 @@ Makes the mouse warp to newly focused windows.
 X and Y coordinates are computed separately, i.e. if moving the mouse only horizontally is enough to put it inside the newly focused window, then it will move only horizontally.
-```
+```kdl
 input {
    warp-mouse-to-focus
 }
@@ -201,7 +201,7 @@ input {
 Focuses windows and outputs automatically when moving the mouse over them.
-```
+```kdl
 input {
    focus-follows-mouse
 }
@@ -211,14 +211,14 @@ input {
 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%"
@@ -232,7 +232,7 @@ If this flag is enabled, switching to the same workspace by index twice will swi
 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
 }
@@ -8,7 +8,7 @@ Key bindings are declared in the `binds {}` section of the config.
 Each bind is a hotkey followed by one action enclosed in curly brackets.
 For example:
-```
+```kdl
 binds {
    Mod+Left { focus-column-left; }
    Super+Alt+L { spawn "swaylock"; }
@@ -53,7 +53,7 @@ For this reason, most of the default keys use the `Mod` modifier.
 <sup>Since: 0.1.8</sup> Binds will repeat by default (i.e. holding down a bind will make it trigger repeatedly).
 You can disable that for specific binds with `repeat=false`:
-```
+```kdl
 binds {
    Mod+T repeat=false { spawn "alacritty"; }
 }
@@ -61,7 +61,7 @@ binds {
 Binds can also have a cooldown, which will rate-limit the bind and prevent it from repeatedly triggering too quickly.
-```
+```kdl
 binds {
    Mod+T cooldown-ms=500 { spawn "alacritty"; }
 }
@@ -74,7 +74,7 @@ This is mostly useful for the scroll bindings.
 You can bind mouse wheel scroll ticks using the following syntax.
 These binds will change direction based on the `natural-scroll` setting.
-```
+```kdl
 binds {
    Mod+WheelScrollDown cooldown-ms=150 { focus-workspace-down; }
    Mod+WheelScrollUp   cooldown-ms=150 { focus-workspace-up; }
@@ -88,7 +88,7 @@ Touchpad scrolling is continuous, so for these binds it is split into discrete i
 These binds are also affected by touchpad's `natural-scroll`, so these example binds are "inverted", since niri has `natural-scroll` enabled for touchpads by default.
-```
+```kdl
 binds {
    Mod+TouchpadScrollDown { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.02+"; }
    Mod+TouchpadScrollUp   { spawn "wpctl" "set-volume" "@DEFAULT_AUDIO_SINK@" "0.02-"; }
@@ -112,7 +112,7 @@ Run a program.
 `spawn` accepts a path to the program binary as the first argument, followed by arguments to the program.
 For example:
-```
+```kdl
 binds {
    // Run alacritty.
    Mod+T { spawn "alacritty"; }
@@ -128,7 +128,7 @@ binds {
 >
 > Spawn bindings have a special `allow-when-locked=true` property that makes them work even while the session is locked:
 >
-> ```
+> ```kdl
 > binds {
 >     // This mute bind will work even when the session is locked.
 >     XF86AudioMute allow-when-locked=true { spawn "wpctl" "set-mute" "@DEFAULT_AUDIO_SINK@" "toggle"; }
@@ -137,23 +137,23 @@ binds {
 Currently, niri *does not* use a shell to run commands, which means that you need to manually separate arguments.
-```
+```kdl
 binds {
    // Correct: every argument is in its own quotes.
    Mod+T { spawn "alacritty" "-e" "/usr/bin/fish"; }
    // Wrong: will interpret the whole `alacritty -e /usr/bin/fish` string as the binary path.
-    Mod+T { spawn "alacritty -e /usr/bin/fish"; }
+    Mod+D { spawn "alacritty -e /usr/bin/fish"; }
    // Wrong: will pass `-e /usr/bin/fish` as one argument, which alacritty won't understand.
-    Mod+T { spawn "alacritty" "-e /usr/bin/fish"; }
+    Mod+Q { spawn "alacritty" "-e /usr/bin/fish"; }
 }
 ```
 This also means that you cannot expand environment variables or `~`.
 If you need this, you can run the command through a shell manually.
-```
+```kdl
 binds {
    // Wrong: no shell expansion here. These strings will be passed literally to the program.
    Mod+T { spawn "grim" "-o" "$MAIN_OUTPUT" "~/screenshot.png"; }
@@ -161,17 +161,17 @@ binds {
    // Correct: run this through a shell manually so that it can expand the arguments.
    // Note that the entire command is passed as a SINGLE argument,
    // because shell will do its own argument splitting by whitespace.
-    Mod+T { spawn "sh" "-c" "grim -o $MAIN_OUTPUT ~/screenshot.png"; }
+    Mod+D { spawn "sh" "-c" "grim -o $MAIN_OUTPUT ~/screenshot.png"; }
    // You can also use a shell to run multiple commands,
    // use pipes, process substitution, and so on.
-    Mod+T { spawn "sh" "-c" "notify-send clipboard \"$(wl-paste)\""; }
+    Mod+Q { spawn "sh" "-c" "notify-send clipboard \"$(wl-paste)\""; }
 }
 ```
 As a special case, niri will expand `~` to the home directory *only* at the beginning of the program name.
-```
+```kdl
 binds {
    // This will work: one ~ at the very beginning.
    Mod+T { spawn "~/scripts/do-something.sh"; }
@@ -182,7 +182,7 @@ binds {
 Exit niri after showing a confirmation dialog to avoid accidentally triggering it.
-```
+```kdl
 binds {
    Mod+Shift+E { quit; }
 }
@@ -190,7 +190,7 @@ binds {
 If you want to skip the confirmation dialog, set the flag like so:
-```
+```kdl
 binds {
    Mod+Shift+E { quit skip-confirmation=true; }
 }
@@ -202,7 +202,7 @@ binds {
 Freeze the screen for a brief moment then crossfade to the new contents.
-```
+```kdl
 binds {
    Mod+Return { do-screen-transition; }
 }
@@ -221,7 +221,7 @@ dconf write /org/gnome/desktop/interface/color-scheme "\"prefer-dark\""
 By default, the screen is frozen for 250 ms to give windows time to redraw, before the crossfade.
 You can set this delay like this:
-```
+```kdl
 binds {
    Mod+Return { do-screen-transition delay-ms=100; }
 }
@@ -4,7 +4,7 @@ In the `layout {}` section you can change various settings that influence how wi
 Here are the contents of this section at a glance:
-```
+```kdl
 layout {
    gaps 16
    center-focused-column "never"
@@ -52,7 +52,7 @@ Set gaps around (inside and outside) windows in logical pixels.
 The value will be rounded to physical pixels according to the scale factor of every output.
 For example, `gaps 0.5` on an output with `scale 2` will result in one physical-pixel wide gaps.
-```
+```kdl
 layout {
    gaps 16
 }
@@ -67,7 +67,7 @@ This can be set to:
 - `"always"`, the focused column will always be centered.
 - `"on-overflow"`, focusing a column will center it if it doesn't fit on screen together with the previously focused column.
-```
+```kdl
 layout {
    center-focused-column "always"
 }
@@ -83,7 +83,7 @@ The default preset widths are <sup>1</sup>&frasl;<sub>3</sub>, <sup>1</sup>&fras
 `fixed` sets the width in logical pixels exactly.
-```
+```kdl
 layout {
    // Cycle between 1/3, 1/2, 2/3 of the output, and a fixed 1280 logical pixels.
    preset-column-widths {
@@ -108,7 +108,7 @@ Set the default width of the new windows.
 The syntax is the same as in `preset-column-widths` above.
-```
+```kdl
 layout {
    // Open new windows sized 1/3 of the output.
    default-column-width { proportion 0.33333; }
@@ -117,7 +117,7 @@ layout {
 You can also leave the brackets empty, then the windows themselves will decide their initial width.
-```
+```kdl
 layout {
    // New windows decide their initial width themselves.
    default-column-width {}
@@ -140,7 +140,7 @@ They are very similar and have the same options.
 The difference is that the focus ring is drawn only around the active window, whereas borders are drawn around all windows and affect their sizes (windows shrink to make space for the borders).
 | Focus Ring                | Border                |
-| ---------- | ------ |
+| ------------------------- | --------------------- |
 | ![](./img/focus-ring.png) | ![](./img/border.png) |
 > [!TIP]
@@ -155,7 +155,7 @@ The difference is that the focus ring is drawn only around the active window, wh
 Focus ring and border have the following options.
-```
+```kdl
 layout {
    // focus-ring has the same options.
    border {
@@ -182,7 +182,7 @@ Set the thickness of the border in logical pixels.
 The value will be rounded to physical pixels according to the scale factor of every output.
 For example, `width 0.5` on an output with `scale 2` will result in one physical-pixel thick borders.
-```
+```kdl
 layout {
    border {
        width 2
@@ -213,7 +213,7 @@ Gradients are rendered the same as CSS [`linear-gradient(angle, from, to)`](http
 The angle works the same as in `linear-gradient`, and is optional, defaulting to `180` (top-to-bottom gradient).
 You can use any CSS linear-gradient tool on the web to set these up, like [this one](https://www.css-gradient.com/).
-```
+```kdl
 layout {
    focus-ring {
        active-gradient from="#80c8ff" to="#bbddff" angle=45
@@ -226,10 +226,10 @@ To do that, set `relative-to="workspace-view"`.
 Here's a visual example:
 | Default                          | `relative-to="workspace-view"`                      |
-| --- | --- |
+| -------------------------------- | --------------------------------------------------- |
 | ![](./img/gradients-default.png) | ![](./img/gradients-relative-to-workspace-view.png) |
-```
+```kdl
 layout {
    border {
        active-gradient from="#ffbb66" to="#ffc880" angle=45 relative-to="workspace-view"
@@ -251,7 +251,7 @@ Top and bottom struts will simply add outer gaps in addition to the area occupie
 The value will be rounded to physical pixels according to the scale factor of every output.
 For example, `top 0.5` on an output with `scale 2` will result in one physical-pixel wide top strut.
-```
+```kdl
 layout {
    struts {
        left 64
@@ -4,7 +4,7 @@ This page documents all top-level options that don't otherwise have dedicated pa
 Here are all of these options at a glance:
-```
+```kdl
 spawn-at-startup "waybar"
 spawn-at-startup "alacritty"
@@ -35,7 +35,7 @@ Add lines like this to spawn processes at niri startup.
 This option works the same way as the `spawn` key binding action, so please read about all its subtleties on the [key bindings](./Configuration:-Key-Bindings.md) page.
-```
+```kdl
 spawn-at-startup "waybar"
 spawn-at-startup "alacritty"
 ```
@@ -58,7 +58,7 @@ With `prefer-no-csd` set, applications that negotiate server-side decorations th
 >
 > Restart applications after changing `prefer-no-csd` in the config to apply it.
-```
+```kdl
 prefer-no-csd
 ```
@@ -71,13 +71,13 @@ The path is formatted with `strftime(3)` to give you the screenshot date and tim
 Niri will create the last folder of the path if it doesn't exist.
-```
+```kdl
 screenshot-path "~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png"
 ```
 You can also set this option to `null` to disable saving screenshots to disk.
-```
+```kdl
 screenshot-path null
 ```
@@ -85,7 +85,7 @@ screenshot-path null
 Override environment variables for processes spawned by niri.
-```
+```kdl
 environment {
    // Set a variable like this:
    // QT_QPA_PLATFORM "wayland"
@@ -99,7 +99,7 @@ environment {
 Change the theme and size of the cursor as well as set the `XCURSOR_THEME` and `XCURSOR_SIZE` environment variables.
-```
+```kdl
 cursor {
    xcursor-theme "breeze_cursors"
    xcursor-size 48
@@ -112,7 +112,7 @@ Settings for the "Important Hotkeys" overlay.
 Set the `skip-at-startup` flag if you don't want to see the hotkey help at niri startup.
-```
+```kdl
 hotkey-overlay {
    skip-at-startup
 }
@@ -4,7 +4,7 @@
 You can declare named workspaces at the top level of the config:
-```
+```kdl
 workspace "browser"
 workspace "chat" {
@@ -18,7 +18,7 @@ Otherwise, they behave like any other workspace: you can move them around, move
 Actions like `focus-workspace` or `move-column-to-workspace` can refer to workspaces by name.
 Also, you can use an `open-on-workspace` window rule to make a window open on a specific named workspace:
-```
+```kdl
 // Declare a workspace named "chat" that opens on the "DP-2" output.
 workspace "chat" {
    open-on-output "DP-2"
@@ -5,7 +5,7 @@ You can disable or adjust this with `output` sections.
 Here's what it looks like with all properties written out:
-```
+```kdl
 output "eDP-1" {
    // off
    mode "1920x1080@120.030"
@@ -30,7 +30,7 @@ Matching by output manufacturer and model is planned, but blocked on Smithay ado
 This flag turns off that output entirely.
-```
+```kdl
 // Turn off that monitor.
 output "HDMI-A-1" {
    off
@@ -49,7 +49,7 @@ If the mode is omitted altogether or doesn't work, niri will try to pick one aut
 Run `niri msg outputs` while inside a niri instance to list all outputs and their modes.
 The refresh rate that you set here must match *exactly*, down to the three decimal digits, to what you see in `niri msg outputs`.
-```
+```kdl
 // Set a high refresh rate for this monitor.
 // High refresh rate monitors tend to use 60 Hz as their preferred mode,
 // requiring a manual mode setting.
@@ -76,7 +76,7 @@ Set the scale of the monitor.
 <sup>Since: 0.1.7</sup> Scale below 0 and above 10 will now fail during config parsing. Scale was previously clamped to these values anyway.
-```
+```kdl
 output "eDP-1" {
    scale 2.0
 }
@@ -89,7 +89,7 @@ Rotate the output counter-clockwise.
 Valid values are: `"normal"`, `"90"`, `"180"`, `"270"`, `"flipped"`, `"flipped-90"`, `"flipped-180"` and `"flipped-270"`.
 Values with `flipped` additionally flip the output.
-```
+```kdl
 output "HDMI-A-1" {
    transform "90"
 }
@@ -107,7 +107,7 @@ The cursor can only move between directly adjacent outputs.
 > For example, a 3840×2160 output with scale 2.0 will have a logical size of 1920×1080, so to put another output directly adjacent to it on the right, set its x to 1920.
 > If the position is unset or results in an overlap, the output is instead placed automatically.
-```
+```kdl
 output "HDMI-A-1" {
    position x=1280 y=0
 }
@@ -140,7 +140,7 @@ You can check whether an output supports VRR in `niri msg outputs`.
 >
 > Some monitors will continuously modeset (flash black) with VRR enabled; I'm not sure if there's a way to fix it.
-```
+```kdl
 output "HDMI-A-1" {
    variable-refresh-rate
 }
@@ -40,10 +40,12 @@ Lines starting with `//` are comments; they are ignored.
 Also, you can put `/-` in front of a section to comment out the entire section:
-```
+```kdl
 /-output "eDP-1" {
-    everything inside here
+    // Everything inside here is ignored.
-    is ignored
+    // The display won't be turned off
    // as the whole section is commented out.
    off
 }
 ```
@@ -53,7 +55,7 @@ Toggle options in niri are commonly represented as flags.
 Writing out the flag enables it, and omitting it or commenting it out disables it.
 For example:
-```
+```kdl
 // "Focus follows mouse" is enabled.
 input {
    focus-follows-mouse
@@ -62,7 +64,7 @@ input {
 }
 ```
-```
+```kdl
 // "Focus follows mouse" is disabled.
 input {
    // focus-follows-mouse
@@ -75,7 +77,7 @@ input {
 Most sections cannot be repeated. For example:
-```
+```kdl
 // This is valid: every section appears once.
 input {
    keyboard {
@@ -88,7 +90,8 @@ input {
 }
 ```
-```
+<!-- no-test -->
 ```kdl
 // This is NOT valid: input section appears twice.
 input {
    keyboard {
@@ -105,7 +108,8 @@ input {
 Exceptions are, for example, sections that configure different devices by name:
-```
+<!-- no-test -->
 ```kdl
 output "eDP-1" {
    // ...
 }
@@ -7,7 +7,7 @@ Window rules are processed in order of appearance in the config file.
 This means that you can put more generic rules first, then override them for specific windows later.
 For example:
-```
+```kdl
 // Set open-maximized to true for all windows.
 window-rule {
    open-maximized true
@@ -26,7 +26,7 @@ window-rule {
 Here are all matchers and properties that a window rule could have:
-```
+```kdl
 window-rule {
    match title="Firefox"
    match app-id="Alacritty"
@@ -77,7 +77,7 @@ window-rule {
 Each window rule can have several `match` and `exclude` directives.
 In order for the rule to apply, a window needs to match *any* of the `match` directives, and *none* of the `exclude` directives.
-```
+```kdl
 window-rule {
    // Match all Telegram windows...
    match app-id=r#"^org\.telegram\.desktop$"#
@@ -93,7 +93,7 @@ window-rule {
 Match and exclude directives have the same syntax.
 There can be multiple *matchers* in one directive, then the window should match all of them for the directive to apply.
-```
+```kdl
 window-rule {
    // Match Firefox windows with Gmail in title.
    match app-id="org.mozilla.firefox" title="Gmail"
@@ -121,7 +121,7 @@ Let's look at the matchers in more detail.
 These are regular expressions that should match anywhere in the window title and app ID respectively.
 You can read about the supported regular expression syntax [here](https://docs.rs/regex/latest/regex/#syntax).
-```
+```kdl
 // Match windows with title containing "Mozilla Firefox",
 // or windows with app ID containing "Alacritty".
 window-rule {
@@ -132,7 +132,7 @@ window-rule {
 Raw KDL strings can be helpful for writing out regular expressions:
-```
+```kdl
 window-rule {
    exclude app-id=r#"^org\.keepassxc\.KeePassXC$"#
 }
@@ -157,7 +157,7 @@ Matches active windows (same windows that have the active border / focus ring co
 Every workspace on the focused monitor will have one active window.
 This means that you will usually have multiple active windows (one per workspace), and when you switch between workspaces, you can see two active windows at once.
-```
+```kdl
 window-rule {
    match is-active=true
 }
@@ -172,7 +172,7 @@ Contrary to `is-active`, there can only be a single focused window.
 Also, when opening a layer-shell application launcher or pop-up menu, the keyboard focus goes to layer-shell.
 While layer-shell has the keyboard focus, windows will not match this rule.
-```
+```kdl
 window-rule {
    match is-focused=true
 }
@@ -188,7 +188,7 @@ Matches the window that is the "active" window in its column.
 Contrary to `is-active`, there is always one `is-active-in-column` window in each column.
 It is the window that was last focused in the column, i.e. the one that will gain focus if this column is focused.
-```
+```kdl
 window-rule {
    match is-active-in-column=true
 }
@@ -203,7 +203,7 @@ Matches during the first 60 seconds after starting niri.
 This is useful for properties like `open-on-output` which you may want to apply only right after starting niri.
-```
+```kdl
 // Open windows on the HDMI-A-1 monitor at niri startup, but not afterwards.
 window-rule {
    match at-startup=true
@@ -221,7 +221,7 @@ To be precise, they apply at the point when niri sends the initial configure req
 Set the default width for the new window.
-```
+```kdl
 // Give Blender and GIMP some guaranteed width on opening.
 window-rule {
    match app-id="^blender$"
@@ -242,7 +242,7 @@ If such an output does not exist, the window will open on the currently focused
 If the window opens on an output that is not currently focused, the window will not be automatically focused.
-```
+```kdl
 // Open Firefox and Telegram (but not its Media Viewer)
 // on a specific monitor.
 window-rule {
@@ -264,7 +264,7 @@ If such a workspace does not exist, the window will open on the currently focuse
 If the window opens on an output that is not currently focused, the window will not be automatically focused.
-```
+```kdl
 // Open Fractal on the "chat" workspace.
 window-rule {
    match app-id=r#"^org\.gnome\.Fractal$"#
@@ -277,7 +277,7 @@ window-rule {
 Make the window open as a maximized column.
-```
+```kdl
 // Maximize Firefox by default.
 window-rule {
    match app-id=r#"^org\.mozilla\.firefox$"#
@@ -290,7 +290,7 @@ window-rule {
 Make the window open fullscreen.
-```
+```kdl
 window-rule {
    open-fullscreen true
 }
@@ -298,7 +298,7 @@ window-rule {
 You can also set this to `false` to *prevent* a window from opening fullscreen.
-```
+```kdl
 // Make the Telegram media viewer open in windowed mode.
 window-rule {
    match app-id=r#"^org\.telegram\.desktop$"# title="^Media viewer$"
@@ -329,7 +329,7 @@ To preview and set up this rule, check the `preview-render` option in the debug
 The built-in screenshot UI is not affected by this problem though.
 If you open the screenshot UI while screencasting, you will be able to select the area to screenshot while seeing all windows normally, but on a screencast the selection UI will display with windows blocked out.
-```
+```kdl
 // Block out password managers from screencasts.
 window-rule {
    match app-id=r#"^org\.keepassxc\.KeePassXC$"#
@@ -345,7 +345,7 @@ This way you avoid accidentally showing the window on a screencast when opening
 This setting will still let you use the interactive built-in screenshot UI, but it will block out the window from the fully automatic screenshot actions, such as `screenshot-screen` and `screenshot-window`.
 The reasoning is that with an interactive selection, you can make sure that you avoid screenshotting sensitive content.
-```
+```kdl
 window-rule {
    block-out-from "screen-capture"
 }
@@ -356,7 +356,7 @@ window-rule {
 >
 > For example, you might try to block out specific Firefox tabs like this:
 >
-> ```
+> ```kdl
 > window-rule {
 >     // Doesn't quite work! Try to block out the Gmail tab.
 >     match app-id=r#"^org\.mozilla\.firefox$"# title="- Gmail "
@@ -382,7 +382,7 @@ Opacity is applied to every surface of the window individually, so subsurfaces a
 Also, focus ring and border with background will show through semitransparent windows (see `prefer-no-csd` and the `draw-border-with-background` window rule below).
-```
+```kdl
 // Make inactive windows semitransparent.
 window-rule {
    match is-active=false
@@ -401,10 +401,10 @@ Set this to `false` to draw them as borders around the window even for windows w
 This property can be useful for rectangular windows that do not support the xdg-decoration protocol.
 | With Background                                  | Without Background                                  |
-| --------------- | ------------------ |
+| ------------------------------------------------ | --------------------------------------------------- |
 | ![](./img/simple-egl-border-with-background.png) | ![](./img/simple-egl-border-without-background.png) |
-```
+```kdl
 window-rule {
    draw-border-with-background false
 }
@@ -421,7 +421,7 @@ These rules have the same options as the normal focus ring and border config in
 However, in addition to `off` to disable the border/focus ring, this window rule has an `on` flag that enables the border/focus ring for the window even if it was otherwise disabled.
 The `on` flag has precedence over the `off` flag, in case both are set.
-```
+```kdl
 window-rule {
    focus-ring {
        off
@@ -446,7 +446,7 @@ Set the corner radius of the window.
 On its own, this setting will only affect the border and the focus ring—they will round their corners to match the geometry corner radius.
 If you'd like to force-round the corners of the window itself, set `clip-to-geometry true` in addition to this setting.
-```
+```kdl
 window-rule {
    geometry-corner-radius 12
 }
@@ -459,7 +459,7 @@ The radius is set in logical pixels, and controls the radius of the window itsel
 Instead of one radius, you can set four, for each corner.
 The order is the same as in CSS: top-left, top-right, bottom-right, bottom-left.
-```
+```kdl
 window-rule {
    geometry-corner-radius 8 8 0 0
 }
@@ -479,7 +479,7 @@ This will cut out any client-side window shadows, and also round window corners
 ![](./img/clip-to-geometry.png)
-```
+```kdl
 window-rule {
    clip-to-geometry true
 }
@@ -489,7 +489,7 @@ Enable border, set `geometry-corner-radius` and `clip-to-geometry`, and you've g
 ![](./img/border-radius-clip.png)
-```
+```kdl
 prefer-no-csd
 layout {
@@ -521,7 +521,7 @@ These values instruct niri to never ask the window to be smaller than the minimu
 >
 > This is a limitation of niri's window height distribution algorithm.
-```
+```kdl
 window-rule {
    min-width 100
    max-width 200
@@ -530,7 +530,7 @@ window-rule {
 }
 ```
-```
+```kdl
 // Fix OBS with server-side decorations missing a minimum width.
 window-rule {
    match app-id=r#"^com\.obsproject\.Studio$"#