Use anchors on the wiki (#1266)

* wiki testing * wiki updates * use .md with anchors, revert sidebar * bump wiki action * add some more anchors, fix some language * change links to be more descriptive by themselves
2026-06-21 02:01:55 +07:00 · 2025-03-15 16:42:05 +01:00
parent 9e560e7e60
commit 392fc27de1
23 changed files with 44 additions and 46 deletions
@@ -239,7 +239,7 @@ jobs:
        with:
          lfs: true
          show-progress: false
-      - uses: Andrew-Chen-Wang/github-wiki-action@86138cbd6328b21d759e89ab6e6dd6a139b22270
+      - uses: Andrew-Chen-Wang/github-wiki-action@b7e552d7cb0fa7f83e459012ffc6840fd87bcb83

  rustdoc:
    needs: build
@@ -21,7 +21,7 @@ window-rule {
 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/wez/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`.
+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
@@ -32,7 +32,7 @@ To fix this, run them with the `_JAVA_AWT_WM_NONREPARENTING=1` environment varia
 ### 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
+It's been fixed in rofi, but [the fix had not been released yet](https://github.com/davatorium/rofi/discussions/2008).

 ### Fullscreen games

@@ -4,7 +4,7 @@ Niri has several options that are only useful for debugging, or are experimental
 They are not meant for normal use.

 > [!CAUTION]
-> These options are **not** covered by the [config breaking change policy](./Configuration:-Overview.md).
+> These options are **not** covered by the [config breaking change policy](./Configuration:-Overview.md#breaking-change-policy).
 > They can change or stop working at any point with little notice.

 Here are all the options at a glance:
@@ -313,7 +313,7 @@ Actions for taking screenshots.
 - `screenshot`: opens the built-in interactive screenshot UI.
 - `screenshot-screen`, `screenshow-window`: takes a screenshot of the focused screen or window respectively.

-The screenshot is both stored to the clipboard and saved to disk, according to the [`screenshot-path` option](./Configuration:-Miscellaneous.md).
+The screenshot is both stored to the clipboard and saved to disk, according to the [`screenshot-path` option](./Configuration:-Miscellaneous#screenshot-path).

 <sup>Since: 25.02</sup> You can disable saving to disk for a specific bind with the `write-to-disk=false` property:

@@ -6,7 +6,7 @@ Layer rules let you adjust behavior for individual layer-shell surfaces.
 They have `match` and `exclude` directives that control which layer-shell surfaces the rule should apply to, and a number of properties that you can set.

 Layer rules are processed and work very similarly to window rules, just with different matchers and properties.
-Please read the [window rules](./Configuration:-Window-Rules.md) wiki page to learn how matching works.
+Please read the [window rules wiki page](./Configuration:-Window-Rules.md) to learn how matching works.

 Here are all matchers and properties that a layer rule could have:

@@ -78,8 +78,7 @@ They will be replaced with solid black rectangles.

 This can be useful for notifications.

-The same caveats and instructions apply as for the `block-out-from` window rule.
-Please read the `block-out-from` section in the [window rules](./Configuration:-Window-Rules.md) wiki page for more details.
+The same caveats and instructions apply as for the [`block-out-from` window rule](./Configuration:-Window-Rules.md#block-out-from), so check the documentation there.

 ![Screenshot showing a notification visible normally, but blocked out on OBS.](./img/layer-block-out-from-screencast.png)

@@ -115,7 +114,7 @@ layer-rule {

 Override the shadow options for the surface.

-These rules have the same options as the normal shadow config in the [layout](./Configuration:-Layout.md) section, so check the documentation there.
+These rules have the same options as the normal [`shadow` config in the layout section](./Configuration:-Layout.md#shadow), so check the documentation there.

 Unlike window shadows, layer surface shadows always need to be enabled with a layer rule.
 That is, enabling shadows in the layout config section won't automatically enable them for layer surfaces.
@@ -208,7 +208,7 @@ layout {
 > `default-column-width {}` causes niri to send a (0, H) size in the initial configure request.
 >
 > This is a bit [unclearly defined](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/issues/155) in the Wayland protocol, so some clients may misinterpret it.
-> Either way, `default-column-width {}` is most useful for specific windows, in form of a [window rule](https://github.com/YaLTeR/niri/wiki/Configuration:-Window-Rules) with the same syntax.
+> Either way, `default-column-width {}` is most useful for specific windows, in form of a [window rule](./Configuration:-Window-Rules.md#default-column-width) with the same syntax.

 ### `preset-window-heights`

@@ -249,10 +249,10 @@ The difference is that the focus ring is drawn only around the active window, wh
 > 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.
+> If you don't like that, you should uncomment the [`prefer-no-csd` setting](./Configuration:-Miscellaneous.md#prefer-no-csd) at the top level 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).
+> Alternatively, you can override this behavior with the [`draw-border-with-background` window rule](./Configuration:-Window-Rules.md#draw-border-with-background).

 Focus ring and border have the following options.

@@ -312,7 +312,7 @@ Similarly to colors, you can set `active-gradient` and `inactive-gradient`, whic

 Gradients are rendered the same as CSS [`linear-gradient(angle, from, to)`](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient).
 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/).
+You can use any CSS linear-gradient tool on the web to set these up, like [css-gradient.com](https://www.css-gradient.com/).

 ```kdl
 layout {
@@ -388,7 +388,7 @@ These will also remove client-side shadows if the window draws any.

 `inactive-color` lets you override the shadow color for inactive windows; by default, a more transparent `color` is used.

-Shadow drawing will follow the window corner radius set with the `geometry-corner-radius` [window rule](https://github.com/YaLTeR/niri/wiki/Configuration:-Window-Rules).
+Shadow drawing will follow the window corner radius set with the [`geometry-corner-radius` window rule](./Configuration:-Window-Rules.md#geometry-corner-radius).

 > [!NOTE]
 > Currently, shadow drawing only supports matching radius for all corners. If you set `geometry-corner-radius` to four values instead of one, the first (top-left) corner radius will be used for shadows.
@@ -40,7 +40,7 @@ Add lines like this to spawn processes at niri startup.

 `spawn-at-startup` accepts a path to the program binary as the first argument, followed by arguments to the program.

-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.
+This option works the same way as the [`spawn` key binding action](./Configuration:-Key-Bindings.md#spawn), so please read about all its subtleties there.

 ```kdl
 spawn-at-startup "waybar"
@@ -170,5 +170,4 @@ hotkey-overlay {
 }
 ```

-You can customize which binds the hotkey overlay shows using the `hotkey-overlay-title` property.
-Check the [key bindings](./Configuration:-Key-Bindings.md) wiki page for details.
+You can customize which binds the hotkey overlay shows using the [`hotkey-overlay-title` property](./Configuration:-Key-Bindings.md#custom-hotkey-overlay-titles).
@@ -143,7 +143,7 @@ You can check whether an output supports VRR in `niri msg outputs`.
 > [!NOTE]
 > Some drivers have various issues with VRR.
 >
-> If the cursor moves at a low framerate with VRR, try setting the `disable-cursor-plane` [debug flag](./Configuration:-Debug-Options.md) and reconnecting the monitor.
+> If the cursor moves at a low framerate with VRR, try setting the [`disable-cursor-plane` debug flag](./Configuration:-Debug-Options.md#disable-cursor-plane) and reconnecting the monitor.
 >
 > If a monitor is not detected as VRR-capable when it should, sometimes unplugging a different monitor fixes it.
 >
@@ -131,7 +131,7 @@ output "eDP-1" {
 ### Defaults

 Omitting most of the sections of the config file will leave you with the default values for that section.
-A notable exception is `binds {}`: they do not get filled with defaults, so make sure you do not erase this section.
+A notable exception is [`binds {}`](./Configuration:-Key-Bindings.md): they do not get filled with defaults, so make sure you do not erase this section.

 ### Breaking Change Policy

@@ -16,7 +16,7 @@ switch-events {
 ```

 The syntax is similar to key bindings.
-Currently, only the `spawn` action are supported.
+Currently, only the [`spawn` action](./Configuration:-Key-Bindings.md#spawn) are supported.

 > [!NOTE]
 > In contrast to key bindings, switch event bindings are *always* executed, even when the session is locked.
@@ -481,7 +481,7 @@ You can block out windows from xdg-desktop-portal screencasts.
 They will be replaced with solid black rectangles.

 This can be useful for password managers or messenger windows, etc.
-For layer-shell notification pop-ups and the like, you can use a `block-out-from` [layer rule](./Configuration:-Layer-Rules.md).
+For layer-shell notification pop-ups and the like, you can use a [`block-out-from` layer rule](./Configuration:-Layer-Rules.md#block-out-from).

 ![Screenshot showing a window visible normally, but blocked out on OBS.](./img/block-out-from-screencast.png)

@@ -547,7 +547,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).

-Opacity can be toggled on or off for a window using the [`toggle-window-rule-opacity`](./Configuration:-Key-Bindings.md) action.
+Opacity can be toggled on or off for a window using the [`toggle-window-rule-opacity`](./Configuration:-Key-Bindings.md#toggle-window-rule-opacity) action.

 ```kdl
 // Make inactive windows semitransparent.
@@ -657,7 +657,7 @@ window-rule {

 Set a scroll factor for all scroll events sent to a window.

-This will be multiplied with the scroll factor set for your input device in the [input](/wiki/Configuration:-Input.md) section.
+This will be multiplied with the scroll factor set for your input device in the [input section](/wiki/Configuration:-Input.md#pointing-devices).

 ```kdl
 // Make scrolling in Firefox a bit slower.
@@ -693,7 +693,7 @@ window-rule {

 Override the focus ring and border options for the window.

-These rules have the same options as the normal focus ring and border config in the [layout](./Configuration:-Layout.md) section, so check the documentation there.
+These rules have the same options as the normal [`focus-ring` and `border` config in the layout section](./Configuration:-Layout.md#focus-ring-and-border), so check the documentation there.

 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.
@@ -720,7 +720,7 @@ window-rule {

 Override the shadow options for the window.

-This rule has the same options as the normal shadow config in the [layout](./Configuration:-Layout.md) section, so check the documentation there.
+This rule has the same options as the normal [`shadow` config in the layout section](./Configuration:-Layout.md#shadow), so check the documentation there.

 However, in addition to `on` to enable the shadow, this window rule has an `off` flag that disables the shadow for the window even if it was otherwise enabled.
 The `on` flag has precedence over the `off` flag, in case both are set.
@@ -742,7 +742,7 @@ window-rule {

 Override the tab indicator options for the window.

-Options in this rule match the same options as the normal tab indicator config in the [layout](./Configuration:-Layout.md) section, so check the documentation there.
+Options in this rule match the same options as the normal [`tab-indicator` config in the layout section](./Configuration:-Layout.md#tab-indicator), so check the documentation there.

 ```kdl
 // Make KeePassXC tab have a dark red inactive color.
@@ -762,7 +762,7 @@ window-rule {
 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.
+If you'd like to force-round the corners of the window itself, set [`clip-to-geometry true`](#clip-to-geometry) in addition to this setting.

 ```kdl
 window-rule {
@@ -803,7 +803,7 @@ window-rule {
 }
 ```

-Enable border, set `geometry-corner-radius` and `clip-to-geometry`, and you've got a classic setup:
+Enable border, set [`geometry-corner-radius`](#geometry-corner-radius) and `clip-to-geometry`, and you've got a classic setup:

 ![](./img/border-radius-clip.png)

@@ -834,7 +834,7 @@ Informs the window that it is tiled.
 Usually, windows will react by becoming rectangular and hiding their client-side shadows.
 Windows that snap their size to a grid (e.g. terminals like [foot](https://codeberg.org/dnkl/foot)) will usually disable this snapping when they are tiled.

-By default, niri will set the tiled state to `true` together with [`prefer-no-csd`](./Configuration:-Miscellaneous.md) in order to improve behavior for apps that don't support server-side decorations.
+By default, niri will set the tiled state to `true` together with [`prefer-no-csd`](./Configuration:-Miscellaneous.md#prefer-no-csd) in order to improve behavior for apps that don't support server-side decorations.
 You can use this window rule to override this, for example to get rectangular windows with CSD.

 ```kdl
@@ -2,7 +2,7 @@ When starting niri from a display manager like GDM, or otherwise through the `ni
 This provides the necessary systemd integration to run programs like `mako` and services like `xdg-desktop-portal` bound to the graphical session.

 Here's an example on how you might set up [`mako`](https://github.com/emersion/mako), [`waybar`](https://github.com/Alexays/Waybar), [`swaybg`](https://github.com/swaywm/swaybg) and [`swayidle`](https://github.com/swaywm/swayidle) to run as systemd services with niri.
-In contrast to the `spawn-at-startup` config option, this lets you easily monitor their status and output, and restart or reload them.
+In contrast to [`spawn-at-startup`](./Configuration:-Miscellaneous.md#spawn-at-startup), this lets you easily monitor their status and output, and restart or reload them.

 1. Install them, i.e. `sudo dnf install mako waybar swaybg swayidle`
 2. Create a `niri.service.wants` folder: `mkdir -p ~/.config/systemd/user/niri.service.wants`
@@ -1,6 +1,6 @@
 ### How to disable client-side decorations/make windows rectangular?

-Uncomment the `prefer-no-csd` setting at the [top level](./Configuration:-Miscellaneous.md) of the config, and then restart your apps.
+Uncomment the [`prefer-no-csd` setting](./Configuration:-Miscellaneous.md#prefer-no-csd) at the top level of the config, and then restart your apps.
 Then niri will ask windows to omit client-side decorations, and also inform them that they are being tiled (which makes some windows rectangular, even if they cannot omit the decorations).

 Note that currently this will prevent edge window resize handles from showing up.
@@ -8,14 +8,14 @@ You can still resize windows by holding <kbd>Mod</kbd> and the right mouse butto

 ### Why is the border/focus ring showing up through semitransparent windows?

-Uncomment the `prefer-no-csd` setting at the [top level](./Configuration:-Miscellaneous.md) of the config, and then restart your apps.
+Uncomment the [`prefer-no-csd` setting](./Configuration:-Miscellaneous.md#prefer-no-csd) at the top level of the config, and then restart your apps.
 Niri will draw focus rings and borders *around* windows that agree to omit their client-side decorations.

 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.

-You can also override this behavior with the `draw-border-with-background` [window rule](./Configuration:-Window-Rules.md).
+You can also override this behavior with the [`draw-border-with-background` window rule](./Configuration:-Window-Rules.md#draw-border-with-background).

 ### How to enable rounded corners for all windows?

@@ -28,7 +28,7 @@ window-rule {
 }
 ```

-For more information, check [this wiki section](https://github.com/YaLTeR/niri/wiki/Configuration:-Window-Rules#geometry-corner-radius).
+For more information, check the [`geometry-corner-radius` window rule](./Configuration:-Window-Rules.md#geometry-corner-radius).

 ### How to hide the "Important Hotkeys" pop-up at the start?

@@ -12,7 +12,7 @@ Also see the [gestures configuration](./Configuration:-Gestures.md) wiki page.

 You can move windows by holding <kbd>Mod</kbd> and the left mouse button.

-You can customize the look of the window insertion preview in the `insert-hint` [layout config](./Configuration:-Layout.md) section.
+You can customize the look of the window insertion preview in the [`insert-hint` layout config](./Configuration:-Layout.md#insert-hint).

 <sup>Since: 25.01</sup> Right click while moving to toggle between floating and tiling layout to put the window into.

@@ -2,7 +2,7 @@ Since niri is not a complete desktop environment, you will very likely want to r

 ### Notification Daemon

-Many apps need one. For example, [mako](https://github.com/emersion/mako) works well. Use [a systemd setup](./Example-systemd-Setup.md) or `spawn-at-startup`.
+Many apps need one. For example, [mako](https://github.com/emersion/mako) works well. Use [a systemd setup](./Example-systemd-Setup.md) or [`spawn-at-startup`](./Configuration:-Miscellaneous.md#spawn-at-startup).

 ### Portals

@@ -14,7 +14,7 @@ Portals **require** [running niri as a session](./Getting-Started.md), which mea
 * `xdg-desktop-portal-gnome`: required for screencasting support.
 * `gnome-keyring`: implements the Secret portal, required for certain apps to work.

-Then systemd should start them on-demand automatically. These particular portals are configured in `niri-portals.conf` which [must be installed](https://github.com/YaLTeR/niri/wiki/Getting-Started#installation) in the correct location.
+Then systemd should start them on-demand automatically. These particular portals are configured in `niri-portals.conf` which [must be installed](./Getting-Started.md#manual-installation) in the correct location.

 Since we're using `xdg-desktop-portal-gnome`, Flatpak apps will read the GNOME UI settings. For example, to enable the dark style, run:

@@ -24,7 +24,7 @@ dconf write /org/gnome/desktop/interface/color-scheme '"prefer-dark"'

 ### Authentication Agent

-Required when apps need to ask for root permissions. Something like `plasma-polkit-agent` works fine. Start it [with systemd](./Example-systemd-Setup.md) or with `spawn-at-startup`.
+Required when apps need to ask for root permissions. Something like `plasma-polkit-agent` works fine. Start it [with systemd](./Example-systemd-Setup.md) or with [`spawn-at-startup`](./Configuration:-Miscellaneous.md#spawn-at-startup).

 Note that to start `plasma-polkit-agent` with systemd on Fedora, you'll need to override its systemd service to add the correct dependency. Run:

@@ -24,7 +24,7 @@ Unlike regular columns, tabbed columns can go full-screen with multiple windows.
 Tabbed columns show a tab indicator on the side.
 You can click on the indicator to switch tabs.

-See the `tab-indicator` section in the [layout](./Configuration:-Layout.md) options to configure it.
+See the [`tab-indicator` section in the layout section](./Configuration:-Layout.md#tab-indicator) to configure it.

 By default, the indicator draws "outside" the column, so it can overlay other windows or go off-screen.
 The `place-within-column` flag puts the indicator "inside" the column, adjusting the window size to make space for it.
@@ -17,7 +17,7 @@ env DISPLAY=:0 flatpak run com.valvesoftware.Steam

 ![xwayland-satellite running Steam and Half-Life.](https://github.com/user-attachments/assets/57db8f96-40d4-4621-a389-373c169349a4)

-You can also automatically run it at startup, and set `DISPLAY` by default for all apps by adding it to the `environment` section of the niri config:
+You can also automatically run it at startup, and set `DISPLAY` by default for all apps by adding it to the [`environment`](./Configuration:-Miscellaneous.md#environment) section of the niri config:

 ```kdl
 spawn-at-startup "xwayland-satellite"
@@ -31,7 +31,7 @@ environment {

 > [!NOTE]
 > If the `:0` DISPLAY is already taken (for example, by some other Xwayland server like `xwayland-run`), `xwayland-satellite` will try the next DISPLAY numbers in order: `:1`, `:2`, etc. and tell you which one it used in its output.
-> Then, you will need to use that DISPLAY number for the `env` command or for the niri `environment` block.
+> Then, you will need to use that DISPLAY number for the `env` command or for the niri [`environment`](./Configuration:-Miscellaneous.md#environment) section.
 >
 > You can also force a specific DISPLAY number like so: `xwayland-satellite :12` will start on `DISPLAY=:12`.

@@ -28,8 +28,8 @@
 * [Debug Options](./Configuration:-Debug-Options.md)

 ## Development
-* [Design Principles](./Design-Principles.md)
-* [Developing niri](./Developing-niri.md)
-* [Fractional Layout](./Fractional-Layout.md)
-* [Redraw Loop](./Redraw-Loop.md)
-* [Animation Timing](./Animation-Timing.md)
+* [Design Principles](./Development:-Design-Principles.md)
+* [Developing niri](./Development:-Developing-niri.md)
+* [Fractional Layout](./Development:-Fractional-Layout.md)
+* [Redraw Loop](./Development:-Redraw-Loop.md)
+* [Animation Timing](./Development:-Animation-Timing.md)