wiki: Add outputs section

3 files changed, 126 insertions, 9 deletions

diff --git a/resources/default-config.kdl b/resources/default-config.kdl
index a996da9f..60848297 100644
--- a/resources/default-config.kdl
+++ b/resources/default-config.kdl
@@ -45,18 +45,13 @@ input {
 // You can configure outputs by their name, which you can find
 // by running `niri msg outputs` while inside a niri instance.
 // The built-in laptop monitor is usually called "eDP-1".
+// Find more information on the wiki:
+// https://github.com/YaLTeR/niri/wiki/Configuration:-Outputs
 // Remember to uncomment the node by removing "/-"!
 /-output "eDP-1" {
     // Uncomment this line to disable this output.
     // off
 
-    // Scale is a floating-point number, but at the moment only integer values work.
-    scale 2.0
-
-    // Transform allows to rotate the output counter-clockwise, valid values are:
-    // normal, 90, 180, 270, flipped, flipped-90, flipped-180 and flipped-270.
-    transform "normal"
-
     // Resolution and, optionally, refresh rate of the output.
     // The format is "<width>x<height>" or "<width>x<height>@<refresh rate>".
     // If the refresh rate is omitted, niri will pick the highest refresh rate
@@ -65,14 +60,21 @@ input {
     // Run `niri msg outputs` while inside a niri instance to list all outputs and their modes.
     mode "1920x1080@120.030"
 
+    // Scale is a floating-point number, but at the moment only integer values work.
+    scale 2.0
+
+    // Transform allows to rotate the output counter-clockwise, valid values are:
+    // normal, 90, 180, 270, flipped, flipped-90, flipped-180 and flipped-270.
+    transform "normal"
+
     // Position of the output in the global coordinate space.
     // This affects directional monitor actions like "focus-monitor-left", and cursor movement.
     // The cursor can only move between directly adjacent outputs.
-    // Output scale has to be taken into account for positioning:
+    // Output scale and rotation has to be taken into account for positioning:
     // outputs are sized in logical, or scaled, pixels.
     // For example, a 3840×2160 output with scale 2.0 will have a logical size of 1920×1080,
     // so to put another output directly adjacent to it on the right, set its x to 1920.
-    // It the position is unset or results in an overlap, the output is instead placed
+    // If the position is unset or results in an overlap, the output is instead placed
     // automatically.
     position x=1280 y=0
 }
diff --git a/wiki/Configuration:-Outputs.md b/wiki/Configuration:-Outputs.md
new file mode 100644
index 00000000..cecd09c6
--- /dev/null
+++ b/wiki/Configuration:-Outputs.md
@@ -0,0 +1,114 @@
+### Overview
+
+By default, niri will attempt to turn on all connected monitors using their preferred modes.
+You can disable or adjust this with `output` sections.
+
+Here's what it looks like with all properties written out:
+
+```
+output "eDP-1" {
+    // off
+    scale 2.0
+    mode "1920x1080@120.030"
+    position x=1280 y=0
+    transform "90"
+}
+
+output "HDMI-A-1" {
+    // ...settings for HDMI-A-1...
+}
+```
+
+Outputs are matched by connector name (i.e. `eDP-1`, `HDMI-A-1`) which you can find by running `niri msg outputs`.
+Usually, the built-in monitor in laptops will be called `eDP-1`.
+Matching by output manufacturer and model is planned, but blocked on Smithay adopting libdisplay-info instead of edid-rs.
+
+### `off`
+
+This flag turns off that output entirely.
+
+```
+// Turn off that monitor.
+output "HDMI-A-1" {
+    off
+}
+```
+
+### `mode`
+
+Set the monitor resolution and refresh rate.
+
+The format is `<width>x<height>` or `<width>x<height>@<refresh rate>`.
+If the refresh rate is omitted, niri will pick the highest refresh rate for the resolution.
+
+If the mode is omitted altogether or doesn't work, niri will try to pick one automatically.
+
+Run `niri msg outputs` while inside a niri instance to list all outputs and their modes.
+
+```
+// Set a high refresh rate for this monitor.
+// High refresh rate monitors tend to use 60 Hz as their preferred mode,
+// requiring a manual mode setting.
+output "HDMI-A-1" {
+    mode "2560x1440@143.912"
+}
+
+// Use a lower resolution on the built-in laptop monitor
+// (for example, for testing purposes).
+output "eDP-1" {
+    mode "1280x720"
+}
+```
+
+### `scale`
+
+Set the scale of the monitor.
+
+This is a floating-point number to enable fractional scaling in the future, but at the moment only integer scale values will work.
+
+```
+output "eDP-1" {
+    scale 2.0
+}
+```
+
+### `transform`
+
+Rotate the output counter-clockwise.
+
+Valid values are: `"normal"`, `"90"`, `"180"`, `"270"`, `"flipped"`, `"flipped-90"`, `"flipped-180"` and `"flipped-270"`.
+Values with `flipped` additionally flip the output.
+
+```
+output "HDMI-A-1" {
+    transform "90"
+}
+```
+
+### `position`
+
+Set the position of the output in the global coordinate space.
+
+This affects directional monitor actions like `focus-monitor-left`, and cursor movement.
+The cursor can only move between directly adjacent outputs.
+
+> [!NOTE]
+> Output scale and rotation has to be taken into account for positioning: outputs are sized in logical, or scaled, pixels.
+> For example, a 3840×2160 output with scale 2.0 will have a logical size of 1920×1080, so to put another output directly adjacent to it on the right, set its x to 1920.
+> If the position is unset or results in an overlap, the output is instead placed automatically.
+
+```
+output "HDMI-A-1" {
+    position x=1280 y=0
+}
+```
+
+#### Automatic Positioning
+
+Niri repositions outputs from scratch every time the output configuration changes (which includes monitors disconnecting and connecting).
+The following algorithm is used for positioning outputs.
+
+1. Collect all connected monitors and their logical sizes.
+1. Sort them by their name. This makes it so the automatic positioning does not depend on the order the monitors are connected. This is important because the connection order is non-deterministic at compositor startup.
+1. Try to place every output with explicitly configured `position`, in order. If the output overlaps previously placed outputs, place it to the right of all previously placed outputs. In this case, niri will also print a warning.
+1. Place every output without explicitly configured `position` by putting it to the right of all previously placed outputs.
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
index 106313f8..014a8b91 100644
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -8,6 +8,7 @@
 ## Configuration
 * [Overview](./Configuration:-Overview.md)
 * [Input](./Configuration:-Input.md)
+* [Outputs](./Configuration:-Outputs.md)
 * [Window Rules](./Configuration:-Window-Rules.md)
 * [Animations](./Configuration:-Animations.md)
 * [Debug Options](./Configuration:-Debug-Options.md)