From dc93f1c1fd7b67e2da5af2ffada732b9ddeb2d6a Mon Sep 17 00:00:00 2001 From: Kent Daleng Date: Sun, 17 Aug 2025 16:05:41 +0200 Subject: 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 --- wiki/Getting-Started.md | 187 ------------------------------------------------ 1 file changed, 187 deletions(-) delete mode 100644 wiki/Getting-Started.md (limited to 'wiki/Getting-Started.md') diff --git a/wiki/Getting-Started.md b/wiki/Getting-Started.md deleted file mode 100644 index 6a20969d..00000000 --- a/wiki/Getting-Started.md +++ /dev/null @@ -1,187 +0,0 @@ -The easiest way to get niri is to install one of the distribution packages. -Here are some of them: [Fedora COPR](https://copr.fedorainfracloud.org/coprs/yalter/niri/) and [nightly COPR](https://copr.fedorainfracloud.org/coprs/yalter/niri-git/) (which I maintain myself), [NixOS Flake](https://github.com/sodiboo/niri-flake), and some more from repology below. -See the [Building](#building) section if you'd like to compile niri yourself and the [Packaging niri](./Packaging-niri.md) page if you want to package niri. - -[![Packaging status](https://repology.org/badge/vertical-allrepos/niri.svg)](https://repology.org/project/niri/versions) - -After installing, start niri from your display manager like GDM. -Press SuperT to run a terminal ([Alacritty]) and SuperD to run an application launcher ([fuzzel]). -To exit niri, press SuperShiftE. - -If you're not using a display manager, you should run `niri-session` (systemd/dinit) or `niri --session` (others) from a TTY. -The `--session` flag will make niri import its environment variables globally into the system manager and D-Bus, and start its D-Bus services. -The `niri-session` script will additionally start niri as a systemd/dinit service, which starts up a graphical session target required by some services like portals. - -You can also run `niri` inside an existing desktop session. -Then it will open as a window, where you can give it a try. -Note that this windowed mode is mainly meant for development, so it is a bit buggy (in particular, there are issues with hotkeys). - -Next, see the [list of important software](./Important-Software.md) required for normal desktop use, like a notification daemon and portals. -Also, check the [configuration introduction](./Configuration:-Introduction.md) page to get started configuring niri. -There you can find links to other pages containing thorough documentation and examples for all options. -Finally, the [Xwayland](./Xwayland.md) page explains how to run X11 applications on niri. - -### NVIDIA - -The NVIDIA drivers currently have an issue with high VRAM usage due to a heap reuse quirk. -You're recommended to apply a manual fix documented [here](./Nvidia.md) if you run niri on an NVIDIA GPU. - -NVIDIA GPUs can have problems running niri (for example, the screen remains black upon starting from a TTY). -Sometimes, the problems can be fixed. -You can try the following: - -1. Update NVIDIA drivers. You need a GPU and drivers recent enough to support GBM. -2. Make sure kernel modesetting is enabled. This usually involves adding `nvidia-drm.modeset=1` to the kernel command line. Find and follow a guide for your distribution. Guides from other Wayland compositors can help. - -### Asahi, ARM, and other kmsro devices - -On some of these systems, niri fails to correctly detect the primary render device. -If you're getting a black screen when starting niri on a TTY, you can try to set the device manually. - -First, find which devices you have: - -``` -$ ls -l /dev/dri/ -drwxr-xr-x@ - root 14 мая 07:07 by-path -crw-rw----@ 226,0 root 14 мая 07:07 card0 -crw-rw----@ 226,1 root 14 мая 07:07 card1 -crw-rw-rw-@ 226,128 root 14 мая 07:07 renderD128 -crw-rw-rw-@ 226,129 root 14 мая 07:07 renderD129 -``` - -You will likely have one `render` device and two `card` devices. - -Open the niri config file at `~/.config/niri/config.kdl` and put your `render` device path like this: - -``` -debug { - render-drm-device "/dev/dri/renderD128" -} -``` - -Save, then try to start niri again. -If you still get a black screen, try using each of the `card` devices. - -### Nix/NixOS - -There's a common problem of mesa drivers going out of sync with niri, so make sure your system mesa version matches the niri mesa version. -When this happens, you usually see a black screen when trying to start niri from a TTY. - -Also, on Intel graphics, you may need a workaround described [here](https://nixos.wiki/wiki/Intel_Graphics). - -### Virtual Machines - -To run niri in a VM, make sure to enable 3D acceleration. - -## Main Default Hotkeys - -When running on a TTY, the Mod key is Super. -When running in a window, the Mod key is Alt. - -The general system is: if a hotkey switches somewhere, then adding Ctrl will move the focused window or column there. - -| Hotkey | Description | -| ------ | ----------- | -| ModShift/ | Show a list of important niri hotkeys | -| ModT | Spawn `alacritty` (terminal) | -| ModD | Spawn `fuzzel` (application launcher) | -| SuperAltL | Spawn `swaylock` (screen locker) | -| ModQ | Close the focused window | -| ModH or Mod← | Focus the column to the left | -| ModL or Mod→ | Focus the column to the right | -| ModJ or Mod↓ | Focus the window below in a column | -| ModK or Mod↑ | Focus the window above in a column | -| ModCtrlH or ModCtrl← | Move the focused column to the left | -| ModCtrlL or ModCtrl→ | Move the focused column to the right | -| ModCtrlJ or ModCtrl↓ | Move the focused window below in a column | -| ModCtrlK or ModCtrl↑ | Move the focused window above in a column | -| ModShiftHJKL or ModShift←↓↑→ | Focus the monitor to the side | -| ModCtrlShiftHJKL or ModCtrlShift←↓↑→ | Move the focused column to the monitor to the side | -| ModU or ModPageDown | Switch to the workspace below | -| ModI or ModPageUp | Switch to the workspace above | -| ModCtrlU or ModCtrlPageDown | Move the focused column to the workspace below | -| ModCtrlI or ModCtrlPageUp | Move the focused column to the workspace above | -| ModShiftU or ModShiftPageDown | Move the focused workspace down | -| ModShiftI or ModShiftPageUp | Move the focused workspace up | -| Mod, | Consume the window to the right into the focused column | -| Mod. | Expel the bottom window in the focused column into its own column | -| Mod[ | Consume or expel the focused window to the left | -| Mod] | Consume or expel the focused window to the right | -| ModR | Toggle between preset column widths | -| ModShiftR | Toggle between preset column heights | -| ModF | Maximize column | -| ModC | Center column within view | -| Mod- | Decrease column width by 10% | -| Mod= | Increase column width by 10% | -| ModShift- | Decrease window height by 10% | -| ModShift= | Increase window height by 10% | -| ModCtrlR | Reset window height back to automatic | -| ModShiftF | Toggle full-screen on the focused window | -| ModV | Move the focused window between the floating and the tiling layout | -| ModShiftV | Switch focus between the floating and the tiling layout | -| PrtSc | Take an area screenshot. Select the area to screenshot with mouse, then press Space to save the screenshot, or Escape to cancel | -| AltPrtSc | Take a screenshot of the focused window to clipboard and to `~/Pictures/Screenshots/` | -| CtrlPrtSc | Take a screenshot of the focused monitor to clipboard and to `~/Pictures/Screenshots/` | -| ModShiftE or CtrlAltDelete | Exit niri | - -## Building - -First, install the dependencies for your distribution. - -- Ubuntu 24.04: - - ```sh - sudo apt-get install -y gcc clang libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev libpango1.0-dev libdisplay-info-dev - ``` - -- Fedora: - - ```sh - sudo dnf install gcc libudev-devel libgbm-devel libxkbcommon-devel wayland-devel libinput-devel dbus-devel systemd-devel libseat-devel pipewire-devel pango-devel cairo-gobject-devel clang libdisplay-info-devel - ``` - -Next, get latest stable Rust: https://rustup.rs/ - -Then, build niri with `cargo build --release`. - -Check Cargo.toml for a list of build features. -For example, you can replace systemd integration with dinit integration using `cargo build --release --no-default-features --features dinit,dbus,xdp-gnome-screencast`. - -> [!WARNING] -> Do NOT build with `--all-features`! -> -> Some features are meant only for development use. -> For example, one of the features enables collection of profiling data into a memory buffer that will grow indefinitely until you run out of memory. - -### NixOS/Nix - -We have a community-maintained flake which provides a devshell with required dependencies. Use `nix build` to build niri, and then run `./results/bin/niri`. - -If you're not on NixOS, you may need [NixGL](https://github.com/nix-community/nixGL) to run the resulting binary: - -``` -nix run --impure github:guibou/nixGL -- ./results/bin/niri -``` - -### Manual Installation - -If installing directly without a package, the recommended file destinations are slightly different. -In this case, put the files in the directories indicated in the table below. -These may vary depending on your distribution. - -Don't forget to make sure that the path to `niri` in niri.service is correct. -This defaults to `/usr/bin/niri`. - -| File | Destination | -| ---- | ----------- | -| `target/release/niri` | `/usr/local/bin/` | -| `resources/niri-session` | `/usr/local/bin/` | -| `resources/niri.desktop` | `/usr/local/share/wayland-sessions/` | -| `resources/niri-portals.conf` | `/usr/local/share/xdg-desktop-portal/` | -| `resources/niri.service` (systemd) | `/etc/systemd/user/` | -| `resources/niri-shutdown.target` (systemd) | `/etc/systemd/user/` | -| `resources/dinit/niri` (dinit) | `/etc/dinit.d/user/` | -| `resources/dinit/niri-shutdown` (dinit) | `/etc/dinit.d/user/` | - -[Alacritty]: https://github.com/alacritty/alacritty -[fuzzel]: https://codeberg.org/dnkl/fuzzel -- cgit