aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--wiki/Application-Issues.md4
-rw-r--r--wiki/Configuration:-Animations.md34
-rw-r--r--wiki/Configuration:-Debug-Options.md39
-rw-r--r--wiki/Configuration:-Input.md24
-rw-r--r--wiki/Configuration:-Key-Bindings.md36
-rw-r--r--wiki/Configuration:-Layout.md34
-rw-r--r--wiki/Configuration:-Miscellaneous.md16
-rw-r--r--wiki/Configuration:-Named-Workspaces.md4
-rw-r--r--wiki/Configuration:-Outputs.md14
-rw-r--r--wiki/Configuration:-Overview.md20
-rw-r--r--wiki/Configuration:-Window-Rules.md62
11 files changed, 138 insertions, 149 deletions
diff --git a/wiki/Application-Issues.md b/wiki/Application-Issues.md
index 695a3f24..82b1088f 100644
--- a/wiki/Application-Issues.md
+++ b/wiki/Application-Issues.md
@@ -20,11 +20,11 @@ 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 {}
}
```
-This empty default column width lets WezTerm pick its own initial width which makes it show up properly. \ No newline at end of file
+This empty default column width lets WezTerm pick its own initial width which makes it show up properly.
diff --git a/wiki/Configuration:-Animations.md b/wiki/Configuration:-Animations.md
index c8b65832..046da29c 100644
--- a/wiki/Configuration:-Animations.md
+++ b/wiki/Configuration:-Animations.md
@@ -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
@@ -169,13 +169,13 @@ If a custom shader fails to compile, niri will print a warning and fall back to
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
@@ -208,7 +208,7 @@ Window closing animation.
This one uses an easing type by default.
-```
+```kdl
animations {
window-close {
duration-ms 150
@@ -229,13 +229,13 @@ If a custom shader fails to compile, niri will print a warning and fall back to
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"
@@ -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
@@ -325,13 +325,13 @@ If a custom shader fails to compile, niri will print a warning and fall back to
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"
@@ -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
diff --git a/wiki/Configuration:-Debug-Options.md b/wiki/Configuration:-Debug-Options.md
index c7367749..a703abdb 100644
--- a/wiki/Configuration:-Debug-Options.md
+++ b/wiki/Configuration:-Debug-Options.md
@@ -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; }
}
diff --git a/wiki/Configuration:-Input.md b/wiki/Configuration:-Input.md
index fd4d0d68..bb000170 100644
--- a/wiki/Configuration:-Input.md
+++ b/wiki/Configuration:-Input.md
@@ -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
@@ -136,7 +136,7 @@ A few settings are common between `touchpad`, `mouse` and `trackpoint`:
- `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`.
+- `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.
Settings specific to `touchpad`s:
@@ -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
}
diff --git a/wiki/Configuration:-Key-Bindings.md b/wiki/Configuration:-Key-Bindings.md
index 37d7344a..24e16cf4 100644
--- a/wiki/Configuration:-Key-Bindings.md
+++ b/wiki/Configuration:-Key-Bindings.md
@@ -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; }
}
diff --git a/wiki/Configuration:-Layout.md b/wiki/Configuration:-Layout.md
index e27d0ef7..04fe04b4 100644
--- a/wiki/Configuration:-Layout.md
+++ b/wiki/Configuration:-Layout.md
@@ -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 {}
@@ -139,23 +139,23 @@ 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 |
-| ---------- | ------ |
+| Focus Ring | Border |
+| ------------------------- | --------------------- |
| ![](./img/focus-ring.png) | ![](./img/border.png) |
> [!TIP]
> By default, focus ring and border are rendered as a solid background rectangle behind windows.
> That is, they will show up through semitransparent windows.
> This is because windows using client-side decorations can have an arbitrary shape.
->
+>
> If you don't like that, you should uncomment the `prefer-no-csd` setting at the [top level](./Configuration:-Miscellaneous.md) of the config.
> Niri will draw focus rings and borders *around* windows that agree to omit their client-side decorations.
->
+>
> Alternatively, you can override this behavior with the `draw-border-with-background` [window rule](https://github.com/YaLTeR/niri/wiki/Configuration:-Window-Rules).
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
@@ -225,11 +225,11 @@ Gradients can be colored relative to windows individually (the default), or to t
To do that, set `relative-to="workspace-view"`.
Here's a visual example:
-| Default | `relative-to="workspace-view"` |
-| --- | --- |
+| 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
diff --git a/wiki/Configuration:-Miscellaneous.md b/wiki/Configuration:-Miscellaneous.md
index 9636c047..7d297d80 100644
--- a/wiki/Configuration:-Miscellaneous.md
+++ b/wiki/Configuration:-Miscellaneous.md
@@ -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
}
diff --git a/wiki/Configuration:-Named-Workspaces.md b/wiki/Configuration:-Named-Workspaces.md
index 4d0ed471..1b63282e 100644
--- a/wiki/Configuration:-Named-Workspaces.md
+++ b/wiki/Configuration:-Named-Workspaces.md
@@ -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"
diff --git a/wiki/Configuration:-Outputs.md b/wiki/Configuration:-Outputs.md
index 6ecf91ab..1adf29fb 100644
--- a/wiki/Configuration:-Outputs.md
+++ b/wiki/Configuration:-Outputs.md
@@ -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
}
diff --git a/wiki/Configuration:-Overview.md b/wiki/Configuration:-Overview.md
index ce5ef9bd..5f3787e2 100644
--- a/wiki/Configuration:-Overview.md
+++ b/wiki/Configuration:-Overview.md
@@ -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
- is ignored
+ // Everything inside here 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" {
// ...
}
diff --git a/wiki/Configuration:-Window-Rules.md b/wiki/Configuration:-Window-Rules.md
index 581931eb..3daceb15 100644
--- a/wiki/Configuration:-Window-Rules.md
+++ b/wiki/Configuration:-Window-Rules.md
@@ -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.