aboutsummaryrefslogtreecommitdiff
path: root/wiki/Configuration:-Introduction.md
diff options
context:
space:
mode:
authorKent Daleng <lolexplode@gmail.com>2025-08-17 16:05:41 +0200
committerGitHub <noreply@github.com>2025-08-17 17:05:41 +0300
commitdc93f1c1fd7b67e2da5af2ffada732b9ddeb2d6a (patch)
treea2f2938a7df17c196be7016dc5fe1fc9f75fb484 /wiki/Configuration:-Introduction.md
parenta6febb86aa5af0df7bf2792ca027ef95a503d599 (diff)
downloadniri-dc93f1c1fd7b67e2da5af2ffada732b9ddeb2d6a.tar.gz
niri-dc93f1c1fd7b67e2da5af2ffada732b9ddeb2d6a.tar.bz2
niri-dc93f1c1fd7b67e2da5af2ffada732b9ddeb2d6a.zip
github wiki replacement / mkdocs-docs (#2147)
* Add wiki based on mkdocs * wording fixes * fix github bg color on narrow * Fix left sidebar section headers being bigger than pages * fix hover accent * fix list rendering on fractional layout * fix videos * fix automatic full links * remove redundant commented css * improve dark mode contrast * update pygments for better child node coloring * update logo * remove blank lines * add systemd language hint --------- Co-authored-by: Ivan Molodetskikh <yalterz@gmail.com>
Diffstat (limited to 'wiki/Configuration:-Introduction.md')
-rw-r--r--wiki/Configuration:-Introduction.md150
1 files changed, 0 insertions, 150 deletions
diff --git a/wiki/Configuration:-Introduction.md b/wiki/Configuration:-Introduction.md
deleted file mode 100644
index 3966a650..00000000
--- a/wiki/Configuration:-Introduction.md
+++ /dev/null
@@ -1,150 +0,0 @@
-### Per-Section Documentation
-
-You can find documentation for various sections of the config on these wiki pages:
-
-* [`input {}`](./Configuration:-Input.md)
-* [`output "eDP-1" {}`](./Configuration:-Outputs.md)
-* [`binds {}`](./Configuration:-Key-Bindings.md)
-* [`switch-events {}`](./Configuration:-Switch-Events.md)
-* [`layout {}`](./Configuration:-Layout.md)
-* [top-level options](./Configuration:-Miscellaneous.md)
-* [`window-rule {}`](./Configuration:-Window-Rules.md)
-* [`layer-rule {}`](./Configuration:-Layer-Rules.md)
-* [`animations {}`](./Configuration:-Animations.md)
-* [`gestures {}`](./Configuration:-Gestures.md)
-* [`debug {}`](./Configuration:-Debug-Options.md)
-
-### Loading
-
-Niri will load configuration from `$XDG_CONFIG_HOME/niri/config.kdl` or `~/.config/niri/config.kdl`, falling back to `/etc/niri/config.kdl`.
-If both of these files are missing, niri will create `$XDG_CONFIG_HOME/niri/config.kdl` with the contents of [the default configuration file](https://github.com/YaLTeR/niri/blob/main/resources/default-config.kdl), which are embedded into the niri binary at build time.
-Please use the default configuration file as the starting point for your custom configuration.
-
-The configuration is live-reloaded.
-Simply edit and save the config file, and your changes will be applied.
-This includes key bindings, output settings like mode, window rules, and everything else.
-
-You can run `niri validate` to parse the config and see any errors.
-
-To use a different config file path, pass it in the `--config` or `-c` argument to `niri`.
-
-You can also set `$NIRI_CONFIG` to the path of the config file.
-`--config` always takes precedence.
-If `--config` or `$NIRI_CONFIG` doesn't point to a real file, the config will not be loaded.
-If `$NIRI_CONFIG` is set to an empty string, it is ignored and the default config location is used instead.
-
-### Syntax
-
-The config is written in [KDL].
-
-#### Comments
-
-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.
- // The display won't be turned off
- // as the whole section is commented out.
- off
-}
-```
-
-#### Flags
-
-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
-
- // Other settings...
-}
-```
-
-```kdl
-// "Focus follows mouse" is disabled.
-input {
- // focus-follows-mouse
-
- // Other settings...
-}
-```
-
-#### Sections
-
-Most sections cannot be repeated. For example:
-
-```kdl
-// This is valid: every section appears once.
-input {
- keyboard {
- // ...
- }
-
- touchpad {
- // ...
- }
-}
-```
-
-```kdl,must-fail
-// This is NOT valid: input section appears twice.
-input {
- keyboard {
- // ...
- }
-}
-
-input {
- touchpad {
- // ...
- }
-}
-```
-
-Exceptions are, for example, sections that configure different devices by name:
-
-<!-- NOTE: this may break in the future -->
-```kdl
-output "eDP-1" {
- // ...
-}
-
-// This is valid: this section configures a different output.
-output "HDMI-A-1" {
- // ...
-}
-
-// This is NOT valid: "eDP-1" already appeared above.
-// It will either throw a config parsing error, or otherwise not work.
-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 {}`](./Configuration:-Key-Bindings.md): they do not get filled with defaults, so make sure you do not erase this section.
-
-### Breaking Change Policy
-
-As a rule, niri updates should not break existing config files.
-(For example, the default config from niri v0.1.0 still parses fine on v25.02 as I'm writing this.)
-
-Exceptions can be made for parsing bugs.
-For example, niri used to accept multiple binds to the same key, but this was not intended and did not do anything (the first bind was always used).
-A patch release changed niri from silently accepting this to causing a parsing failure.
-This is not a blanket rule, I will consider the potential impact of every breaking change like this before deciding to carry on with it.
-
-Keep in mind that the breaking change policy applies only to niri releases.
-Commits between releases can and do occasionally break the config as new features are ironed out.
-However, I do try to limit these, since several people are running git builds.
-
-[KDL]: https://kdl.dev/