diff options
Diffstat (limited to 'wiki/Configuration:-Introduction.md')
| -rw-r--r-- | wiki/Configuration:-Introduction.md | 150 |
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/ |
