docs(readme): show a config example and list every config key
- commit
- 0b8594d3e281d711e11463f27f1e4eb7bb68a3f7
- author
- brice · · 2026-09-26 16:03 UTC
- parent
- ef5b565
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +52 -1
M README.md +52 -1
| @@ -25,6 +25,25 @@ NeferWL does a few things and does them fast. No animations, no themes, no built | |||
| 25 | 25 | - **Light.** A running session uses about 40–80 MB of RAM with two 4K monitors, and near-zero CPU when nothing changes on screen. | |
| 26 | 26 | - **Live config.** One flat `key = value` file. Every key applies on save, keyboard layout included; windows stay open. | |
| 27 | 27 | ||
| 28 | + | A complete desktop in a few lines: | |
| 29 | + | ||
| 30 | + | ```text | |
| 31 | + | keyboard.layout = fr | |
| 32 | + | terminal = foot | |
| 33 | + | startup = waybar | |
| 34 | + | ||
| 35 | + | output.DP-1 = 3840x2160@144 | |
| 36 | + | output.DP-1.scale = 3/2 | |
| 37 | + | ||
| 38 | + | layout.max-columns = 3 | |
| 39 | + | ||
| 40 | + | # A hidden dev workspace: editor and terminal, started and placed for you. | |
| 41 | + | workspace.dev.hidden = on | |
| 42 | + | workspace.dev.column.1 = 67%, code --new-window | |
| 43 | + | workspace.dev.column.2 = 33%, foot | |
| 44 | + | bind.cmd+d = workspace dev | |
| 45 | + | ``` | |
| 46 | + | ||
| 28 | 47 | ### The performance path | |
| 29 | 48 | ||
| 30 | 49 | Every Wayland protocol NeferWL implements is there because it saves work or latency: | |
| @@ -85,7 +104,39 @@ bind.ctrl+cmd+space = spawn fuzzel | |||
| 85 | 104 | startup = wl-paste --watch cliphist store | |
| 86 | 105 | ``` | |
| 87 | 106 | ||
| 88 | - | See `examples/config` for every key and its default. A missing file means defaults. An invalid line logs a warning and keeps that key's default; the rest of the file still applies. Every key applies live when the file changes, including the keyboard layout; each reload logs the keys that changed. | |
| 107 | + | ### Keys | |
| 108 | + | ||
| 109 | + | | Key | Default | Meaning | | |
| 110 | + | |---|---|---| | |
| 111 | + | | `keyboard.layout`, `.variant`, `.options` | empty | xkb names, e.g. `fr`, `caps:escape` | | |
| 112 | + | | `keyboard.repeat-rate` / `repeat-delay` | `25` / `600` | Key repeat per second / delay in ms | | |
| 113 | + | | `keyboard.cmd` | `super` | Modifier that `cmd` means in binds: `super`, `alt` or `ctrl` | | |
| 114 | + | | `terminal` | `foot` | Opened at startup and by `spawn-terminal` | | |
| 115 | + | | `startup` | none | Command run once at session start; repeat the key for more | | |
| 116 | + | | `xwayland` | `xwayland-satellite` | X11 support; `off` disables it | | |
| 117 | + | | `background` | `#111111` | Solid background color | | |
| 118 | + | | `border.width` | `2` | Separator lines between tiles, in logical pixels; `0` hides them | | |
| 119 | + | | `border.active` / `border.inactive` | `#808080` / `#111111` | Separator colors around the focused / other windows | | |
| 120 | + | | `layout.gaps` | `0` | Space between windows | | |
| 121 | + | | `layout.max-columns` | `2` | Columns that share the screen before scrolling | | |
| 122 | + | | `layout.overflow` | `scroll` | Past the max: `scroll` right, or `fixed` spiral split | | |
| 123 | + | | `layout.presets` | `1/3, 1/2, 2/3, 1` | Widths for `cycle-column-width` | | |
| 124 | + | | `focus.follow-move` | `off` | Follow a column moved to another workspace | | |
| 125 | + | | `workspace.<name>.hidden` | `off` | Reachable only through its bind, which toggles it | | |
| 126 | + | | `workspace.<name>.monitor` | focused | Home monitor: connector (`DP-2`) or monitor key | | |
| 127 | + | | `workspace.<name>.max-columns`, `.overflow` | layout values | Per-workspace layout | | |
| 128 | + | | `workspace.<name>.column.<N>` | none | Slot: `<width>, <command>` | | |
| 129 | + | | `output.<name>` | preferred | `WxH`, `WxH@Hz`, `preferred` or `off` | | |
| 130 | + | | `output.<name>.scale` | `1` | 1 to 4, e.g. `1.5` or `4/3` | | |
| 131 | + | | `output.<name>.primary` | `off` | Gets focus and pointer at startup | | |
| 132 | + | | `render.direct-scanout` | `on` | Fullscreen buffers straight to the display | | |
| 133 | + | | `render.tearing` / `render.vrr` | `on` / `on` | For games in direct scanout | | |
| 134 | + | | `log.level` / `log.debug` | `info` / empty | Log level / debug components or `all` | | |
| 135 | + | | `bind.<keys>` | see below | Action for a key combo; `none` removes a default | | |
| 136 | + | ||
| 137 | + | Bind actions: `spawn <command>`, `spawn-terminal`, `close-window`, `toggle-fullscreen`, `cycle-column-width`, `focus-column-left/right`, `focus-window-up/down`, `move-column-left/right`, `consume-or-expel-window-left/right`, `focus-workspace <N>`, `focus-workspace-up/down`, `workspace <name>`, `move-column-to-workspace <N|up|down>`, `move-window-to-workspace <N|up|down>`, `focus-monitor-left/right`, `move-workspace-to-monitor-left/right`, `scale-up`, `scale-down`, `quit`. | |
| 138 | + | ||
| 139 | + | See `examples/config` for every default bind, with comments. A missing file means defaults. An invalid line logs a warning and keeps that key's default; the rest of the file still applies. Every key applies live when the file changes, including the keyboard layout; each reload logs the keys that changed. | |
| 89 | 140 | ||
| 90 | 141 | ## Running commands | |
| 91 | 142 | ||
| @@ -25,6 +25,25 @@ NeferWL does a few things and does them fast. No animations, no themes, no built | |||||
| 25 | - **Light.** A running session uses about 40–80 MB of RAM with two 4K monitors, and near-zero CPU when nothing changes on screen. | 25 | - **Light.** A running session uses about 40–80 MB of RAM with two 4K monitors, and near-zero CPU when nothing changes on screen. | ||
| 26 | - **Live config.** One flat `key = value` file. Every key applies on save, keyboard layout included; windows stay open. | 26 | - **Live config.** One flat `key = value` file. Every key applies on save, keyboard layout included; windows stay open. | ||
| 27 | 27 | ||||
| 28 | + | A complete desktop in a few lines: | |||
| 29 | + | ||||
| 30 | + | ```text | |||
| 31 | + | keyboard.layout = fr | |||
| 32 | + | terminal = foot | |||
| 33 | + | startup = waybar | |||
| 34 | + | ||||
| 35 | + | output.DP-1 = 3840x2160@144 | |||
| 36 | + | output.DP-1.scale = 3/2 | |||
| 37 | + | ||||
| 38 | + | layout.max-columns = 3 | |||
| 39 | + | ||||
| 40 | + | # A hidden dev workspace: editor and terminal, started and placed for you. | |||
| 41 | + | workspace.dev.hidden = on | |||
| 42 | + | workspace.dev.column.1 = 67%, code --new-window | |||
| 43 | + | workspace.dev.column.2 = 33%, foot | |||
| 44 | + | bind.cmd+d = workspace dev | |||
| 45 | + | ``` | |||
| 46 | + | ||||
| 28 | ### The performance path | 47 | ### The performance path | ||
| 29 | 48 | ||||
| 30 | Every Wayland protocol NeferWL implements is there because it saves work or latency: | 49 | Every Wayland protocol NeferWL implements is there because it saves work or latency: | ||
| @@ -85,7 +104,39 @@ bind.ctrl+cmd+space = spawn fuzzel | |||||
| 85 | startup = wl-paste --watch cliphist store | 104 | startup = wl-paste --watch cliphist store | ||
| 86 | ``` | 105 | ``` | ||
| 87 | 106 | ||||
| 88 | - | See `examples/config` for every key and its default. A missing file means defaults. An invalid line logs a warning and keeps that key's default; the rest of the file still applies. Every key applies live when the file changes, including the keyboard layout; each reload logs the keys that changed. | 107 | + | ### Keys |
| 108 | + | ||||
| 109 | + | | Key | Default | Meaning | | |||
| 110 | + | |---|---|---| | |||
| 111 | + | | `keyboard.layout`, `.variant`, `.options` | empty | xkb names, e.g. `fr`, `caps:escape` | | |||
| 112 | + | | `keyboard.repeat-rate` / `repeat-delay` | `25` / `600` | Key repeat per second / delay in ms | | |||
| 113 | + | | `keyboard.cmd` | `super` | Modifier that `cmd` means in binds: `super`, `alt` or `ctrl` | | |||
| 114 | + | | `terminal` | `foot` | Opened at startup and by `spawn-terminal` | | |||
| 115 | + | | `startup` | none | Command run once at session start; repeat the key for more | | |||
| 116 | + | | `xwayland` | `xwayland-satellite` | X11 support; `off` disables it | | |||
| 117 | + | | `background` | `#111111` | Solid background color | | |||
| 118 | + | | `border.width` | `2` | Separator lines between tiles, in logical pixels; `0` hides them | | |||
| 119 | + | | `border.active` / `border.inactive` | `#808080` / `#111111` | Separator colors around the focused / other windows | | |||
| 120 | + | | `layout.gaps` | `0` | Space between windows | | |||
| 121 | + | | `layout.max-columns` | `2` | Columns that share the screen before scrolling | | |||
| 122 | + | | `layout.overflow` | `scroll` | Past the max: `scroll` right, or `fixed` spiral split | | |||
| 123 | + | | `layout.presets` | `1/3, 1/2, 2/3, 1` | Widths for `cycle-column-width` | | |||
| 124 | + | | `focus.follow-move` | `off` | Follow a column moved to another workspace | | |||
| 125 | + | | `workspace.<name>.hidden` | `off` | Reachable only through its bind, which toggles it | | |||
| 126 | + | | `workspace.<name>.monitor` | focused | Home monitor: connector (`DP-2`) or monitor key | | |||
| 127 | + | | `workspace.<name>.max-columns`, `.overflow` | layout values | Per-workspace layout | | |||
| 128 | + | | `workspace.<name>.column.<N>` | none | Slot: `<width>, <command>` | | |||
| 129 | + | | `output.<name>` | preferred | `WxH`, `WxH@Hz`, `preferred` or `off` | | |||
| 130 | + | | `output.<name>.scale` | `1` | 1 to 4, e.g. `1.5` or `4/3` | | |||
| 131 | + | | `output.<name>.primary` | `off` | Gets focus and pointer at startup | | |||
| 132 | + | | `render.direct-scanout` | `on` | Fullscreen buffers straight to the display | | |||
| 133 | + | | `render.tearing` / `render.vrr` | `on` / `on` | For games in direct scanout | | |||
| 134 | + | | `log.level` / `log.debug` | `info` / empty | Log level / debug components or `all` | | |||
| 135 | + | | `bind.<keys>` | see below | Action for a key combo; `none` removes a default | | |||
| 136 | + | ||||
| 137 | + | Bind actions: `spawn <command>`, `spawn-terminal`, `close-window`, `toggle-fullscreen`, `cycle-column-width`, `focus-column-left/right`, `focus-window-up/down`, `move-column-left/right`, `consume-or-expel-window-left/right`, `focus-workspace <N>`, `focus-workspace-up/down`, `workspace <name>`, `move-column-to-workspace <N|up|down>`, `move-window-to-workspace <N|up|down>`, `focus-monitor-left/right`, `move-workspace-to-monitor-left/right`, `scale-up`, `scale-down`, `quit`. | |||
| 138 | + | ||||
| 139 | + | See `examples/config` for every default bind, with comments. A missing file means defaults. An invalid line logs a warning and keeps that key's default; the rest of the file still applies. Every key applies live when the file changes, including the keyboard layout; each reload logs the keys that changed. | |||
| 89 | 140 | ||||
| 90 | ## Running commands | 141 | ## Running commands | ||
| 91 | 142 | ||||