docs(mkdocs): updates for v0.1.22

LGUG2Z · Mar 4, 2024 · 9c8a50f · 9c8a50f
1 parent 41e9068
commit 9c8a50f
Show file tree

Hide file tree

Showing 19 changed files with 324 additions and 56 deletions.
diff --git a/docs/cli/alt-focus-hack.md b/docs/cli/alt-focus-hack.md
@@ -1,7 +1,7 @@
 # alt-focus-hack
 
 ```
-Enable or disable a hack simulating ALT key presses to ensure focus changes succeed
+DEPRECATED since v0.1.22
 
 Usage: komorebic.exe alt-focus-hack <BOOLEAN_STATE>
 

diff --git a/docs/cli/change-layout.md b/docs/cli/change-layout.md
@@ -7,7 +7,7 @@ Usage: komorebic.exe change-layout <DEFAULT_LAYOUT>
 
 Arguments:
   <DEFAULT_LAYOUT>
-          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack]
+          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack, grid]
 
 Options:
   -h, --help

diff --git a/docs/cli/check.md b/docs/cli/check.md
@@ -1,7 +1,7 @@
 # check
 
 ```
-Output various important komorebi-related environment values
+Check komorebi configuration and related files for common errors
 
 Usage: komorebic.exe check
 

diff --git a/docs/cli/configuration.md b/docs/cli/configuration.md
@@ -0,0 +1,12 @@
+# configuration
+
+```
+Show the path to komorebi.json
+
+Usage: komorebic.exe configuration
+
+Options:
+  -h, --help
+          Print help
+
+```
diff --git a/docs/cli/docgen.md b/docs/cli/docgen.md
diff --git a/docs/cli/named-workspace-layout-rule.md b/docs/cli/named-workspace-layout-rule.md
@@ -13,7 +13,7 @@ Arguments:
           The number of window containers on-screen required to trigger this layout rule
 
   <LAYOUT>
-          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack]
+          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack, grid]
 
 Options:
   -h, --help

diff --git a/docs/cli/named-workspace-layout.md b/docs/cli/named-workspace-layout.md
@@ -10,7 +10,7 @@ Arguments:
           Target workspace name
 
   <VALUE>
-          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack]
+          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack, grid]
 
 Options:
   -h, --help

diff --git a/docs/cli/subscribe.md → docs/cli/subscribe-pipe.md b/docs/cli/subscribe.md → docs/cli/subscribe-pipe.md
@@ -1,9 +1,9 @@
-# subscribe
+# subscribe-pipe
 
 ```
-Subscribe to komorebi events
+Subscribe to komorebi events using a Named Pipe
 
-Usage: komorebic.exe subscribe <NAMED_PIPE>
+Usage: komorebic.exe subscribe-pipe <NAMED_PIPE>
 
 Arguments:
   <NAMED_PIPE>

diff --git a/docs/cli/subscribe-socket.md b/docs/cli/subscribe-socket.md
@@ -0,0 +1,16 @@
+# subscribe-socket
+
+```
+Subscribe to komorebi events using a Unix Domain Socket
+
+Usage: komorebic.exe subscribe-socket <SOCKET>
+
+Arguments:
+  <SOCKET>
+          Name of the socket to send event notifications to
+
+Options:
+  -h, --help
+          Print help
+
+```
diff --git a/docs/cli/unsubscribe.md → docs/cli/unsubscribe-pipe.md b/docs/cli/unsubscribe.md → docs/cli/unsubscribe-pipe.md
@@ -1,9 +1,9 @@
-# unsubscribe
+# unsubscribe-pipe
 
 ```
 Unsubscribe from komorebi events
 
-Usage: komorebic.exe unsubscribe <NAMED_PIPE>
+Usage: komorebic.exe unsubscribe-pipe <NAMED_PIPE>
 
 Arguments:
   <NAMED_PIPE>

diff --git a/docs/cli/unsubscribe-socket.md b/docs/cli/unsubscribe-socket.md
@@ -0,0 +1,16 @@
+# unsubscribe-socket
+
+```
+Unsubscribe from komorebi events
+
+Usage: komorebic.exe unsubscribe-socket <SOCKET>
+
+Arguments:
+  <SOCKET>
+          Name of the socket to stop sending event notifications to
+
+Options:
+  -h, --help
+          Print help
+
+```
diff --git a/docs/cli/whkdrc.md b/docs/cli/whkdrc.md
@@ -0,0 +1,12 @@
+# whkdrc
+
+```
+Show the path to whkdrc
+
+Usage: komorebic.exe whkdrc
+
+Options:
+  -h, --help
+          Print help
+
+```
diff --git a/docs/cli/workspace-layout-rule.md b/docs/cli/workspace-layout-rule.md
@@ -16,7 +16,7 @@ Arguments:
           The number of window containers on-screen required to trigger this layout rule
 
   <LAYOUT>
-          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack]
+          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack, grid]
 
 Options:
   -h, --help

diff --git a/docs/cli/workspace-layout.md b/docs/cli/workspace-layout.md
@@ -13,7 +13,7 @@ Arguments:
           Workspace index on the specified monitor (zero-indexed)
 
   <VALUE>
-          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack]
+          [possible values: bsp, columns, rows, vertical-stack, horizontal-stack, ultrawide-vertical-stack, grid]
 
 Options:
   -h, --help

diff --git a/docs/common-workflows/remove-gaps.md b/docs/common-workflows/remove-gaps.md
@@ -2,13 +2,15 @@
 
 If you would like to remove all gaps by default, both between windows
 themselves, and between the monitor edges and the windows, you can set the
-following two configuration options to `0` in the `komorebi.json` configuration
-file.
+following configuration options to `0` and `-1` in the `komorebi.json`
+configuration file.
 
 ```json
 {
   "default_workspace_padding": 0,
-  "default_container_padding": 0
+  "default_container_padding": 0,
+  "border_width": 0,
+  "border_offset": -1
 }
 ```
 

diff --git a/docs/example-configurations.md b/docs/example-configurations.md
@@ -16,6 +16,12 @@ the example files have been downloaded. For most new users this will be in the
 komorebic quickstart
 ```
 
+With the example configurations downloaded, you can now start `komorebi` and `whkd.
+
+```powershell
+komorebic start --whkd
+```
+
 ## komorebi.json
 
 The example window manager configuration sets some sane defaults and provides
@@ -139,6 +145,19 @@ If you have an ultrawide monitor, I recommend using this layout.
 +-----+-----------+-----+
 ```
 
+### Grid
+If you like the `grid` layout in [LeftWM](https://github.com/leftwm/leftwm-layouts) this is almost exactly the same!
+
+```
++-----+-----+   +---+---+---+   +---+---+---+   +---+---+---+
+|     |     |   |   |   |   |   |   |   |   |   |   |   |   |
+|     |     |   |   |   |   |   |   |   |   |   |   |   +---+
++-----+-----+   |   +---+---+   +---+---+---+   +---+---|   |
+|     |     |   |   |   |   |   |   |   |   |   |   |   +---+
+|     |     |   |   |   |   |   |   |   |   |   |   |   |   |
++-----+-----+   +---+---+---+   +---+---+---+   +---+---+---+
+  4 windows       5 windows       6 windows       7 windows
+```
 
 ## whkdrc
 

diff --git a/docs/release/v0-1-22.md b/docs/release/v0-1-22.md
@@ -0,0 +1,56 @@
+In addition to the [changelog](https://github.com/LGUG2Z/komorebi/releases/tag/v0.1.21) of new features and fixes,
+please note the following changes from `v0.1.21` to adjust your configuration files accordingly.
+
+## tl;dr
+
+The way windows are sized and drawn has been improved to remove the need to manually specify and remove invisible
+borders for applications that overflow them. If you use the active window border, the first time you launch `v0.1.22`
+you may end up with a _huge_ border due to these changes.
+
+`active_window_border_width` and `active_window_border_offset` have been renamed to `border_width` and `border_offset`
+as they now also apply outside the context of the active window border.
+
+```json
+{
+  "active_window_border": true,
+  "border_width": 8,
+  "border_offset": -1
+}
+```
+
+Users of the active window border should start from these settings and read the notes below before making further
+adjustments.
+
+## Changes to `active_window_border`, and window sizing:
+
+- The border no longer creates a second drop-shadow around the active window
+- Windows are now sized to fill the layout region entirely, ignoring window decorations such as drop shadows
+- Border offset now starts exactly at the paint edge of the window on all sides
+- Windows are sized such that the border offset and border width are taken into account
+
+## Recommended patterns
+
+### Gapless
+
+- Disable "transparency effects" Personalization > Colors
+- Set the following settings in `komorebi.json`:
+```json
+{
+  "default_workspace_padding": 0,
+  "default_container_padding": 0,
+  "border_offset": -1,
+  "border_width": 0
+}
+```
+
+### 1px border
+
+A 1px border is drawn around the window edge. Users may see a gap for a single pixel, if the system theme has a
+transparent edge - this is the windows themed edge, and is not present for all applications.
+
+```json
+  {
+  "border_offset": 0,
+  "border_width": 1
+}
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -62,17 +62,23 @@ nav:
     - common-workflows/custom-layouts.md
     - common-workflows/dynamic-layout-switching.md
 #    - common-workflows/autohotkey.md
+  - Release notes:
+    - release/v0-1-22.md
   - Configuration reference: https://komorebi.lgug2z.com/schema
   - CLI reference:
     - cli/quickstart.md
     - cli/start.md
     - cli/stop.md
     - cli/check.md
+    - cli/configuration.md
+    - cli/whkdrc.md
     - cli/state.md
     - cli/visible-windows.md
     - cli/query.md
-    - cli/subscribe.md
-    - cli/unsubscribe.md
+    - cli/subscribe-socket.md
+    - cli/unsubscribe-socket.md
+    - cli/subscribe-pipe.md
+    - cli/unsubscribe-pipe.md
     - cli/log.md
     - cli/quick-save-resize.md
     - cli/quick-load-resize.md
@@ -160,7 +166,6 @@ nav:
     - cli/reload-configuration.md
     - cli/watch-configuration.md
     - cli/complete-configuration.md
-    - cli/alt-focus-hack.md
     - cli/window-hiding-behaviour.md
     - cli/cross-monitor-move-behaviour.md
     - cli/toggle-cross-monitor-move-behaviour.md