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>

1 files changed, 150 insertions, 0 deletions

diff --git a/docs/wiki/Configuration:-Introduction.md b/docs/wiki/Configuration:-Introduction.md
new file mode 100644
index 00000000..3966a650
--- /dev/null
+++ b/docs/wiki/Configuration:-Introduction.md
@@ -0,0 +1,150 @@
+### 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/