docs(mkdocs): add common workflows section

2026-04-25 01:58:51 +02:00 · 2024-02-11 17:45:12 -08:00
parent 9a6f831d51
commit 2e0c7430ef
13 changed files with 379 additions and 574 deletions
--- a/README.md
+++ b/README.md
@@ -33,15 +33,7 @@ Tiling Window Management for Windows.
 - [Charitable Donations](#charitable-donations)
 - [GitHub Sponsors](#github-sponsors)
 - [Demonstrations](#demonstrations)
 - [Description](#description)
 - [Design](#design)
 - [Getting Started](#getting-started)
  - [Quickstart](#quickstart)
  - [GitHub Releases](#github-releases)
  - [Building from Source](#building-from-source)
  - [Running](#running)
  - [Configuring](#configuring)
  - [Common First-Time Tips](#common-first-time-tips)
 - [Development](#development)
 - [Logs and Debugging](#logs-and-debugging)
  - [Restoring Windows](#restoring-windows)
@@ -55,46 +47,53 @@ Tiling Window Management for Windows.
 ## About
-_komorebi_ is a tiling window manager that works as an extension to
+_komorebi_ is a tiling window manager that works as an extension to Microsoft's
-Microsoft's [Desktop Window Manager](https://docs.microsoft.com/en-us/windows/win32/dwm/dwm-overview) in Windows 10 and
+[Desktop Window
-above.
+Manager](https://docs.microsoft.com/en-us/windows/win32/dwm/dwm-overview) in
 Windows 10 and above.
-_komorebi_ allows you to control application windows, virtual workspaces and display monitors with a CLI which can be
+_komorebi_ allows you to control application windows, virtual workspaces and
-used with third-party software such as [AutoHotKey](https://github.com/Lexikos/AutoHotkey_L) to set user-defined
+display monitors with a CLI which can be used with third-party software such as
 [AutoHotKey](https://github.com/Lexikos/AutoHotkey_L) to set user-defined
 keyboard shortcuts.
-_komorebi_ aims to make _as few modifications as possible_ to the operating system and desktop environment by default.
+_komorebi_ aims to make _as few modifications as possible_ to the operating
-Users are free to make such modifications in their own configuration files for _komorebi_, but these will remain
+system and desktop environment by default. Users are free to make such
-opt-in and off-by-default for the foreseeable future.
+modifications in their own configuration files for _komorebi_, but these will
 remain opt-in and off-by-default for the foreseeable future.
-Translations of this document can be found in the project wiki:
+There is a [Discord server](https://discord.gg/mGkn66PHkx) available for
-
+_komorebi_-related discussion, help, troubleshooting etc. If you have any
- [komorebi 中文用户指南](https://github.com/LGUG2Z/komorebi/wiki/README-zh) (by [@crosstyan](https://github.com/crosstyan))
+specific feature requests or bugs to report, please create an issue in this
 There is a [Discord server](https://discord.gg/mGkn66PHkx) available for _komorebi_-related discussion, help,
 troubleshooting etc. If you have any specific feature requests or bugs to report, please create an issue in this
 repository.
-There is a [YouTube channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg) where I livestream development
+There is a [YouTube
-on _komorebi_. If you would like to be notified of upcoming livestreams please subscribe and turn on
+channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg) where I post
-notifications. Videos of previous livestreams are also made available in
+_komorebi_ development videos. If you would like to be notified of upcoming
-a [dedicated playlist](https://www.youtube.com/playlist?list=PLllZnrEJu89Cpu4tMO8LAg1m6gWYWLSGJ).
+videos please subscribe and turn on notifications.
-Articles, blog posts, demos, and videos about _komorebi_ can be added to this list by PR:
+Articles, blog posts, demos, and videos about _komorebi_ can be added to this
 list by PR:
 - [Moving to Windows from Linux Pt 1](https://kvwu.io/posts/moving-to-windows/)
 - [Windows 下的现代化平铺窗口管理器 komorebi](https://zhuanlan.zhihu.com/p/455064481)
 - [komorebi を導入してみる](https://zenn.dev/omochice/articles/50f42a3df8f426)
 ## Getting Started
 A [detailed quickstart
 guide](https://lgug2z.github.io/komorebi/installation.html) is available on the
 documentation website.
 ## Charitable Donations
-_komorebi_ is a free and open-source project, and one that encourages you to make charitable donations if
+_komorebi_ is a free and open-source project, and one that encourages you to
-you find the software to be useful and have the financial means.
+make charitable donations if you find the software to be useful and have the
 financial means.
 I encourage you to make a charitable donation to the [Palestine Children's
-Relief Fund](https://pcrf1.app.neoncrm.com/forms/gaza-recovery) and [Fresh
+Relief Fund](https://pcrf1.app.neoncrm.com/forms/gaza-recovery) before you
-Start Refugee](https://www.freshstartrefugee.org/donate) before you consider
+consider sponsoring me on GitHub.
 sponsoring me on GitHub.
 ## Project Sponsorship
@@ -123,546 +122,6 @@ widget enabled. The original video can be viewed
 https://user-images.githubusercontent.com/13164844/163496414-a9cde3d1-b8a7-4a7a-96fb-a8985380bc70.mp4
 ## Description
 _komorebi_ only responds to [WinEvents](https://docs.microsoft.com/en-us/windows/win32/winauto/event-constants) and the
 messages it receives on a dedicated socket.
 _komorebic_ is a CLI that writes messages on _komorebi_'s socket.
 _komorebi_ doesn't handle any keyboard or mouse inputs; a third party program (e.g.
 [whkd](https://github.com/LGUG2Z/whkd)) is needed in order to translate keyboard and mouse events to _komorebic_ commands.
 This architecture, popularised by [_bspwm_](https://github.com/baskerville/bspwm) on Linux and
 [_yabai_](https://github.com/koekeishiya/yabai) on macOS, is outlined as follows:
 ```
          PROCESS                SOCKET
 whkd/ahk  -------->  komorebic  <------>  komorebi
 ```
 ## Design
 _komorebi_ holds a list of physical monitors.
 A monitor is just a rectangle of the available work area which contains one or more virtual workspaces.
 A workspace holds a list of containers.
 A container is just a rectangle where one or more application windows can be displayed.
 This means that:
 - Every monitor has its own collection of virtual workspaces
 - Workspaces only know about containers and their dimensions, not about individual application windows
 - Every application window must belong to a container, even if that container only contains one application window
 - Many application windows can be stacked and cycled through in the same container within a workspace
 ## Getting Started
 ### Quickstart
 It highly recommended that you enable support for long paths in Windows by running the following command in an
 Administrator Terminal before starting with this quickstart guide:
 ```powershell
 Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1
 ```
 Make sure that you have either the [Scoop Package Manager](https://scoop.sh) or WinGet installed, then run the following
 commands at a PowerShell prompt. If you are using WinGet, make sure that you open a new terminal window or reload your
 profile after running the installation steps. Since this is not required when using `scoop`, I personally recommend that
 you use `scoop` for this process.
 As of v0.1.17, the quickstart recommends the use of a static configuration file. If you would like to see older versions
 of this quickstart which recommend the use of dynamic configuration scripts, please refer to
 the [README file of v0.1.16](https://github.com/LGUG2Z/komorebi/tree/v0.1.16).
 ```powershell
 # if using scoop
 scoop bucket add extras
 scoop install whkd
 scoop install komorebi
 # if using winget
 winget install LGUG2Z.whkd
 winget install LGUG2Z.komorebi
 # save the example configuration to ~/komorebi.json
 iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.example.json -OutFile "$Env:USERPROFILE\komorebi.json"
 # save the latest generated app-specific config tweaks and fixes
 komorebic fetch-app-specific-configuration
 # ensure the ~/.config folder exists
 mkdir "$Env:USERPROFILE\.config" -ea 0
 # save the sample whkdrc file with key bindings to ~/.config/whkdrc
 iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/whkdrc.sample -OutFile "$Env:USERPROFILE\.config\whkdrc"
 # start komorebi and whkd
 komorebic start -c "$Env:USERPROFILE\komorebi.json" --whkd
 ```
 Thanks to [@sitiom](https://github.com/sitiom) for getting _komorebi_ added to both the popular Scoop Extras bucket and
 to WinGet.
 You can watch a walkthrough video of this quickstart below on YouTube.
 [![Watch the quickstart walkthrough video](https://img.youtube.com/vi/hDDxtvpjpHs/hqdefault.jpg)](https://www.youtube.com/watch?v=hDDxtvpjpHs)
 #### Using Autohotkey
 If you would like to use Autohotkey, please make sure you have AutoHotKey v2 installed.
 Generally, users who opt for AHK will have specific needs that can only be addressed by the advanced functionality of AHK,
 and so they are assumed to be able to craft their own configuration files.
 If you would like to try out AHK, a simple sample configuration powered by `komorebic.lib.ahk` is provided as a starting
 point. This sample configuration does not take into account the use of a static configuration file; if you choose to use
 a static configuration file alongside AHK, you can remove all the configuration options from your `komorebi.ahk` and use
 it solely to handle hotkey bindings.
 ```powershell
 # save the latest generated komorebic library to ~/komorebic.lib.ahk
 iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebic.lib.ahk -OutFile $Env:USERPROFILE\komorebic.lib.ahk
 # save the latest generated app-specific config tweaks and fixes to ~/komorebi.generated.ahk
 iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.generated.ahk -OutFile $Env:USERPROFILE\komorebi.generated.ahk
 # save the sample komorebi configuration file to ~/komorebi.ahk
 iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.sample.ahk -OutFile $Env:USERPROFILE\komorebi.ahk
 ```
 ### GitHub Releases
 Prebuilt binaries are available on the [releases page](https://github.com/LGUG2Z/komorebi/releases) in a `zip` archive.
 Once downloaded, you will need to move the `komorebi.exe` and `komorebic.exe` binaries to a directory in your `Path` (
 you can see these directories by running `$Env:Path.split(";")` at a PowerShell prompt).
 ### Building from Source
 If you prefer to compile _komorebi_ from source, you will need
 a [working Rust development environment on Windows 10/11](https://rustup.rs/). The `x86_64-pc-windows-msvc` toolchain is
 required, so make sure you have also installed
 the [Build Tools for Visual Studio 2019](https://stackoverflow.com/a/55603112).
 You can then clone this repo and compile the source code to install the binaries for `komorebi` and `komorebic`:
 ```powershell
 cargo install --path komorebi --locked
 cargo install --path komorebic --locked
 ```
 ### Running
 `komorebi` can be run in two ways, using either a static configuration file or a dynamic configuration script.
 The quickstart covers running with a static configuration file.
 If you would like to use a dynamic configuration script, ensure that you have a `komorebi.ps1` or `komorebi.ahk` file
 present, run `komorebic start --await-configuration` at a Powershell prompt, and you will see the following output:
 ```
 Start-Process komorebi.exe -ArgumentList '--await-configuration' -WindowStyle hidden
 Waiting for komorebi.exe to start...Started!
 ```
 This means that `komorebi` is now running in the background, tiling all your windows, and listening for commands sent to
 it by `komorebic`. You can similarly stop the process by running `komorebic stop`.
 For further information on running with a dynamic configuration script, please refer to
 the quickstart section in the [README file of v0.1.16](https://github.com/LGUG2Z/komorebi/tree/v0.1.16)
 ### Configuring
 If you followed the quickstart, `komorebi.json` will be the single place where you declaratively configure the behaviour
 of the window manager. There is a [complete JSON Schema for this configuration file](schema.json) available to provide
 users with auto-completions in their editors.
 If you are running with a dynamic configuration script as recommended in v0.1.16 and earlier, `komorebi` will find the
 sample `komorebi.ps1` file in your `$Env:USERPROFILE` directory and automatically load it. This file also starts `whkd` using the sample `whkdrc` file
 in your `$Env:USERPROFILE\.config` directory.
 Alternatively, if you have AutoHotKey installed and a `komorebi.ahk` file in `$Env:UserProfile` directory, `komorebi`
 will automatically try to load it when starting.
 #### Migrating to a Static Configuration File
 If you have been using `komorebi` with a dynamic configuration script and wish to migrate to using a static
 configuration file, once you have `komorebi` running in the desired configuration state, you can
 run `komorebic generate-static-config`.
 This will print a static configuration that mostly represents your current configuration to the terminal.
 There are four configuration options that you may need to set yourself, if you make use of them:
 - Custom layouts paths for workspaces
 - Custom layout rules for workspaces
 - The applications.yaml path
 - Any individual application rules you have that are not in applications.yaml
 [![Watch the tutorial video](https://img.youtube.com/vi/yqCAOJgL3C0/hqdefault.jpg)](https://www.youtube.com/watch?v=yqCAOJgL3C0)
 #### Configuration with `komorebic`
 As previously mentioned, this project does not handle anything related to keybindings and shortcuts directly. I
 personally use [`whkd`](https://github.com/LGUG2Z/whkd) to manage my window management shortcuts, and have provided a
 sample [whkdrc](whkdrc.sample) configuration that you can use as a starting point for your own.
 You can run `komorebic.exe` to get a full list of the commands that you can use to customise `komorebi` and create
 keybindings with. You can run `komorebic.exe <COMMAND> --help` to get a full explanation of the arguments required for
 each command.
 You can run any configuration command in the `komorebi.ps1` file, and you can bind any action command to your desired
 key combinations in the `whkdrc` file.
 #### AutoHotKey Helper Library for `komorebic`
 ❗️**NOTE**: This section is only relevant for people who wish to use AutoHotKey instead of [`whkd`](https://github.com/LGUG2Z/whkd).
 ❗️**NOTE**: This helper library is only compatible with AutoHotKey v1.1, not with AutoHotKey v2.
 Additionally, you may run `komorebic.exe ahk-library` to generate a helper library for AutoHotKey which wraps
 every `komorebic` command in a native AHK function.
 The output of this command is in AHKv1 syntax. It must be manually converted to AHKv2 syntax
 using [this tool](https://github.com/mmikeww/AHK-v2-script-converter) or something similar.
 If you include the generated library at the top of your `~/komorebi.ahk` configuration file, you will be able to call
 any of the functions that it contains.
 #### Using Different AHK Executables
 ❗️**NOTE**: This section is only relevant for people who wish to use AutoHotKey instead of [`whkd`](https://github.com/LGUG2Z/whkd).
 The preferred way to install AutoHotKey for use with `komorebi` is to install it via `scoop`:
 ```powershell
 scoop bucket add versions
 scoop install autohotkey
 ```
 If you install AutoHotKey using a different method, the name of the executable file may differ from the name given by
 `scoop`, and thus what is expected by default in `komorebi`.
 You may override the executable that `komorebi` looks for to launch and reload `komorebi.ahk` configuration files by
 setting the `$Env:KOMOREBI_AHK_EXE` environment variable.
 Please keep in mind that even when setting a custom executable name using these environment variables, the executables
 are still required to be in your `Path`.
 ### Common First-Time Tips
 #### Setting a Custom KOMOREBI_CONFIG_HOME Directory
 If you do not want to keep _komorebi_-related files in your `$Env:USERPROFILE` directory, you can specify a custom directory
 by setting the `$Env:KOMOREBI_CONFIG_HOME` environment variable.
 For example, to use the `~/.config/komorebi` directory:
 ```powershell
 # Run this command to make sure that the directory has been created
 mkdir -p ~/.config/komorebi
 # Run this command to open up your PowerShell profile configuration in Notepad
 notepad $PROFILE
 # Add this line (with your login user!) to the bottom of your PowerShell profile configuration
 $Env:KOMOREBI_CONFIG_HOME = 'C:\Users\LGUG2Z\.config\komorebi'
 # Save the changes and then reload the PowerShell profile
 . $PROFILE
 ```
 If you already have configuration files that you wish to keep, move them to the `~/.config/komorebi` directory.
 The next time you run `komorebic start`, any files created by or loaded by _komorebi_ will be placed or expected to
 exist in this folder.
 #### Generating Common Application-Specific Configurations
 ❗️**NOTE**: This section is only relevant for people who use dynamic configuration scripts.
 A curated selection of application-specific configurations can be generated to
 help ease the setup for first-time users.
 [`komorebi-application-specific-configuration`](https://github.com/LGUG2Z/komorebi-application-specific-configuration)
 contains YAML definitions of settings that are known to make tricky
 applications behave as expected. These YAML definitions can be used to generate
 a `ps1` or an `ahk` file which you can import at the start of your own `komorebi.ps1` or `komorebi.ahk` files,
 leaving you to focus primarily on your desired keybindings and workspace
 configurations.
 If you have settings for an application that you think should be part of this
 curated selection, please open a PR on the configuration repository.
 In the event that your PR is not accepted, or if you find there are any
 settings that you wish to override, this can easily be done using an override
 file.
 ```powershell
 # Clone and enter the repository
 git clone https://github.com/LGUG2Z/komorebi-application-specific-configuration.git
 cd komorebi-application-specific-configuration
 # Use komorebic to generate a ps1 file
 komorebic.exe pwsh-app-specific-configuration applications.yaml
 # Application-specific generated configuration written to C:\Users\LGUG2Z\.config\komorebi\komorebi.generated.ps1
 # Or use komorebic to generate an ahk file
 komorebic.exe ahk-app-specific-configuration applications.yaml
 # Application-specific generated configuration written to C:\Users\LGUG2Z\.config\komorebi\komorebi.generated.ahk
 #
 # You can include the generated configuration at the top of your komorebi.ahk config with this line:
 #
 # #Include %A_ScriptDir%\komorebi.generated.ahk
 # Optionally, provide an override file that follows the same schema as the second argument
 komorebic.exe pwsh-app-specific-configuration applications.yaml overrides.yaml
 ```
 #### Adding an Active Window Border
 If you would like to add a visual border around the currently focused window, two commands are available:
 ```powershell
 komorebic.exe active-window-border [enable|disable]
 komorebic.exe active-window-border-colour [R G B] --window-kind single
 # optionally, if you want a different colour for stacks of windows
 komorebic.exe active-window-border-colour [R G B] --window-kind stack
 # optionally, if you want a different colour for windows in monocle mode
 komorebic.exe active-window-border-colour [R G B] --window-kind monocle
 ```
 It is important to note that the active window border will only apply to windows managed by `komorebi`.
 [![Watch the tutorial video](https://img.youtube.com/vi/ywiAvoMV_gE/hqdefault.jpg)](https://www.youtube.com/watch?v=ywiAvoMV_gE)
 #### Removing Gaps
 If you would like to remove all gaps from a given workspace, both between windows themselves, and between the monitor edges and the windows, you can set the following two configuration options to `0` for the desired monitors and workspaces:
 ```powershell
 komorebic.exe container-padding <MONITOR_INDEX> <WORKSPACE_INDEX> 0
 komorebic.exe workspace-padding <MONITOR_INDEX> <WORKSPACE_INDEX> 0
 ```
 [![Watch the tutorial video](https://img.youtube.com/vi/eGr07mymgWE/hqdefault.jpg)](https://www.youtube.com/watch?v=eGr07mymgWE)
 #### Multiple Layout Changes on Startup
 ❗️**NOTE**: This section is only relevant for people who use dynamic configuration scripts.
 Depending on what is in your configuration, when `komorebi` is started, you may experience the layout rapidly being adjusted
 with many retile events.
 If you would like to avoid this, you can start `komorebi` with a flag which tells `komorebi` to wait until all configuration
 has been loaded before listening to and responding to window manager events: `komorebic start --await-configuration`.
 If you start `komorebi` with the `--await-configuration` flag, you _must_ send the `komorebic complete-configuration`
 command at the end of the configuration section of your `komorebi.ps1` (or `komorebi.ahk` config, before you start
 defining the key bindings). The layout will not be updated and `komorebi` will not respond to `komorebic` commands until
 this command has been received.
 #### Floating Windows
 ❗️**NOTE**: A significant number of floating window rules for the most common applications are
 [already generated for you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations)
 Sometimes you will want a specific application to never be tiled, and instead float all the time. You can add rules to
 enforce this behaviour:
 ```powershell
 komorebic.exe float-rule title "Control Panel"
 # komorebic.exe float-rule exe [EXE NAME]
 # komorebic.exe float-rule class [CLASS NAME]
 ```
 #### Windows Not Getting Managed
 ❗️**NOTE**: A significant number of force-manage window rules for the most common applications are
 [already generated for you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations)
 In some rare cases, a window may not automatically be registered to be managed by `komorebi`. When this happens, you can
 manually add a rule to force `komorebi` to manage it:
 ```powershell
 komorebic.exe manage-rule exe TIM.exe
 # komorebic.exe manage-rule class [CLASS NAME]
 # komorebic.exe manage-rule title [TITLE]
 ```
 #### Tray Applications
 ❗️**NOTE**: A significant number of tray application rules for the most common applications are
 [already generated for you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations)
 If you are experiencing behaviour where
 [closing a window leaves a blank tile, but minimizing the same window does not](https://github.com/LGUG2Z/komorebi/issues/6)
 , you have probably enabled a 'close/minimize to tray' option for that application. You can tell _komorebi_ to handle
 this application appropriately by identifying it via the executable name or the window class:
 ```powershell
 komorebic.exe identify-tray-application exe Discord.exe
 # komorebic.exe identify-tray-application class [CLASS NAME]
 # komorebic.exe identify-tray-application title [TITLE]
 ```
 #### Microsoft Office Applications
 ❗️**NOTE**: Microsoft Office-specific application rules are
 [already generated for you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations)
 Microsoft Office applications such as Word and Excel require certain configuration options to be set in order to be
 managed correctly. Below is an example of configuring Microsoft Word to be managed correctly by _komorebi_.
 ```powershell
 # This only needs to be added once
 komorebic.exe float-rule class _WwB
 # Repeat these for other office applications such as EXCEL.EXE etc
 # Note that the capitalised EXE is important here- double check the
 # exact case for the name and the file extension in Task Manager or
 # the AHK Window Spy
 komorebic.exe identify-layered-application exe WINWORD.EXE
 komorebic.exe identify-border-overflow-application exe WINWORD.EXE
 ```
 #### Focus Follows Mouse
 `komorebi` supports two focus-follows-mouse implementations; the native Windows Xmouse implementation, which treats the
 desktop, the task bar, and the system tray as windows and switches focus to them eagerly, and a custom `komorebi`
 implementation, which only considers windows managed by `komorebi` as valid targets to switch focus to when moving the
 mouse.
 To enable the `komorebi` implementation you must start the process with the `--ffm` flag to explicitly enable the feature.
 This is because the mouse tracking required for this feature significantly increases the CPU usage of the process (on my
 machine, it jumps from <1% to ~4~), and this CPU increase persists regardless of whether focus-follows-mouse is enabled
 or disabled at any given time via `komorebic`'s configuration commands.
 When calling any of the `komorebic` commands related to focus-follows-mouse functionality, the `windows`
 implementation will be chosen as the default implementation. You can optionally specify the `komorebi` implementation by
 passing it as an argument to the `--implementation` flag:
 ```powershell
 komorebic.exe toggle-focus-follows-mouse --implementation komorebi
 ```
 #### Mouse Follows Focus
 By default, the mouse will move to the center of the window when the focus is changed in a given direction. This
 behaviour is know is 'mouse follows focus'. To disable this behaviour across all workspaces, add the following command
 to your configuration file:
 ```powershell
 komorebic.exe mouse-follows-focus disable
 ```
 [![Watch the tutorial video](https://img.youtube.com/vi/LBoyXQiNINc/hqdefault.jpg)](https://www.youtube.com/watch?v=LBoyXQiNINc)
 #### Saving and Loading Resized Layouts
 If you create a BSP layout through various resize adjustments that you want to be able to restore easily in the future,
 it is possible to "quicksave" that layout to the system's temporary folder and load it later in the same session, or
 alternatively, you may save it to a specific file to be loaded again at any point in the future.
 ```powershell
 komorebic.exe quick-save # saves the focused workspace to $Env:TEMP\komorebi.quicksave.json
 komorebic.exe quick-load # loads $Env:TEMP\komorebi.quicksave.json on the focused workspace
 komorebic.exe save ~/layouts/primary.json # saves the focused workspace to $Env:USERPROFILE\layouts\primary.json
 komorebic.exe load ~/layouts/secondary.json # loads $Env:USERPROFILE\layouts\secondary.json on the focused workspace
 ```
 These layouts can be applied to arbitrary collections of windows on any workspace, as they only track the layout
 dimensions and are not coupled to the applications that were running at the time of saving.
 When layouts that expect more or less windows than the number currently on the focused workspace are loaded, `komorebi`
 will automatically reconcile the difference.
 #### Creating and Loading Custom Layouts
 Particularly for users of ultrawide monitors, traditional tiling layouts may not seem like the most efficient use of
 screen space. If you feel this is the case with any of the default layouts, you are also welcome to create your own
 custom layouts and save them as JSON or YAML.
 If you're not comfortable writing the layouts directly in JSON or YAML, you can use
 the [komorebi Custom Layout Generator](https://lgug2z.github.io/komorebi-custom-layout-generator/) to interactively
 define a custom layout, and then copy the generated JSON content.
 Custom layouts can be loaded on the current workspace or configured for a specific workspace with the following
 commands:
 ```powershell
 komorebic.exe load-custom-layout ~/custom.yaml
 komorebic.exe workspace-custom-layout 0 0 ~/custom.yaml
 ```
 The fundamental building block of a custom _komorebi_ layout is the Column.
 Columns come in three variants:
 - **Primary**: This is where your primary focus will be on the screen most of the time. There must be exactly one Primary
  Column in any custom layout. Optionally, you can specify the percentage of the screen width that you want the Primary
  Column to occupy.
 - **Secondary**: This is an optional column that can either be full height of split horizontally into a fixed number of
  maximum rows. There can be any number of Secondary Columns in a custom layout.
 - **Tertiary**: This is the final column where any remaining windows will be split horizontally into rows as they get added.
 If there is only one window on the screen when a custom layout is selected, that window will take up the full work area
 of the screen.
 If the number of windows is equal to or less than the total number of columns defined in a custom layout, the windows
 will be arranged in an equal-width columns.
 When the number of windows is greater than the number of columns defined in the custom layout, the windows will begin to
 be arranged according to the constraints set on the Primary and Secondary columns of the layout.
 Here is an example custom layout that can be used as a starting point for your own:
 YAML
 ```yaml
 - column: Secondary
  configuration: !Horizontal 2 # max number of rows
 - column: Primary
  configuration: !WidthPercentage 50 # percentage of screen
 - column: Tertiary
  configuration: Horizontal
 ```
 [![Watch the tutorial video](https://img.youtube.com/vi/SgmBHKEOcQ4/hqdefault.jpg)](https://www.youtube.com/watch?v=SgmBHKEOcQ4)
 #### Dynamically Changing Layouts Based on Number of Visible Window Containers
 With `komorebi` it is possible to define rules to automatically change the layout on a specified workspace when a
 threshold of window containers is met.
 ```powershell
 # On the first workspace of the first monitor (0 0)
 # When there are one or more window containers visible on the screen (1)
 # Use the bsp layout (bsp)
 komorebic workspace-layout-rule 0 0 1 bsp
 # On the first workspace of the first monitor (0 0)
 # When there are five or more window containers visible on the screen (five)
 # Use the custom layout stored in the home directory (~/custom.yaml)
 komorebic workspace-custom-layout-rule 0 0 5 ~/custom.yaml
 ```
 However, if you add workspace layout rules, you will not be able to manually change the layout of a workspace until all
 layout rules for that workspace have been cleared.
 ```powershell
 # If you decide that workspace layout rules are not for you, you can remove them from that same workspace like this
 komorebic clear-workspace-layout-rules 0 0
 ```
 ## Development
 If you would like to contribute code to this repository, there are a few requests that I have to ensure a foundation of
--- a/docs/common-workflows/active-window-border.md
+++ b/docs/common-workflows/active-window-border.md
@@ -0,0 +1,40 @@
 # Active Window Border
 If you would like to add a visual border around the currently focused window,
 ensure the following options are defined in the `komorebi.json` configuration
 file.
 ```json
 {
  "active_window_border": true,
  "active_window_border_colours": {
    "single": {
      "r": 66,
      "g": 165,
      "b": 245
    },
    "stack": {
      "r": 256,
      "g": 165,
      "b": 66
    },
    "monocle": {
      "r": 255,
      "g": 51,
      "b": 153
    }
  }
 }
 ```
 It is important to note that the active window border will only apply to
 windows managed by `komorebi`.
 This feature is not considered stable and you may encounter visual artifacts
 from time to time.
 <!-- TODO: Record a new video -->
 [![Watch the tutorial
 video](https://img.youtube.com/vi/ywiAvoMV_gE/hqdefault.jpg)](https://www.youtube.com/watch?v=ywiAvoMV_gE)
--- a/docs/common-workflows/autohotkey.md
+++ b/docs/common-workflows/autohotkey.md
@@ -0,0 +1,30 @@
 # AutoHotKey
 <!-- TODO: Update this completely -->
 If you would like to use Autohotkey, please make sure you have AutoHotKey v2
 installed.
 Generally, users who opt for AHK will have specific needs that can only be
 addressed by the advanced functionality of AHK, and so they are assumed to be
 able to craft their own configuration files.
 If you would like to try out AHK, a simple sample configuration powered by
 `komorebic.lib.ahk` is provided as a starting point. This sample configuration
 does not take into account the use of a static configuration file; if you
 choose to use a static configuration file alongside AHK, you can remove all the
 configuration options from your `komorebi.ahk` and use it solely to handle
 hotkey bindings.
 ```powershell
 # save the latest generated komorebic library to ~/komorebic.lib.ahk
 iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebic.lib.ahk -OutFile $Env:USERPROFILE\komorebic.lib.ahk
 # save the latest generated app-specific config tweaks and fixes to ~/komorebi.generated.ahk
 iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.generated.ahk -OutFile $Env:USERPROFILE\komorebi.generated.ahk
 # save the sample komorebi configuration file to ~/komorebi.ahk
 iwr https://raw.githubusercontent.com/LGUG2Z/komorebi/v0.1.19/komorebi.sample.ahk -OutFile $Env:USERPROFILE\komorebi.ahk
 ```
--- a/docs/common-workflows/custom-layouts.md
+++ b/docs/common-workflows/custom-layouts.md
@@ -0,0 +1,70 @@
 # Custom Layouts
 Particularly for users of ultrawide monitors, traditional tiling layouts may
 not seem like the most efficient use of screen space. If you feel this is the
 case with any of the default layouts, you are also welcome to create your own
 custom layouts and save them as JSON or YAML.
 If you're not comfortable writing the layouts directly in JSON or YAML, you can
 use the [komorebi Custom Layout
 Generator](https://lgug2z.github.io/komorebi-custom-layout-generator/) to
 interactively define a custom layout, and then copy the generated JSON content.
 Custom layouts can be loaded on the current workspace or configured for a
 specific workspace in the `komorebi.json` configuration file.
 ```json
 {
  "monitors": [
    {
      "workspaces": [
        {
          "name": "personal",
          "custom_layout": "C:/Users/LGUG2Z/my-custom-layout.json"
        },
      ]
    }
  ]
 }
 ```
 The fundamental building block of a custom _komorebi_ layout is the Column.
 Columns come in three variants:
 - **Primary**: This is where your primary focus will be on the screen most of
  the time. There must be exactly one Primary Column in any custom layout.
  Optionally, you can specify the percentage of the screen width that you want
  the Primary Column to occupy.
 - **Secondary**: This is an optional column that can either be full height of
  split horizontally into a fixed number of maximum rows. There can be any
  number of Secondary Columns in a custom layout.
 - **Tertiary**: This is the final column where any remaining windows will be
  split horizontally into rows as they get added.
 If there is only one window on the screen when a custom layout is selected,
 that window will take up the full work area of the screen.
 If the number of windows is equal to or less than the total number of columns
 defined in a custom layout, the windows will be arranged in an equal-width
 columns.
 When the number of windows is greater than the number of columns defined in the
 custom layout, the windows will begin to be arranged according to the
 constraints set on the Primary and Secondary columns of the layout.
 Here is an example custom layout that can be used as a starting point for your
 own:
 ```yaml
 - column: Secondary
  configuration: !Horizontal 2 # max number of rows
 - column: Primary
  configuration: !WidthPercentage 50 # percentage of screen
 - column: Tertiary
  configuration: Horizontal
 ```
 <!-- TODO: Record a new video -->
 [![Watch the tutorial video](https://img.youtube.com/vi/SgmBHKEOcQ4/hqdefault.jpg)](https://www.youtube.com/watch?v=SgmBHKEOcQ4)
--- a/docs/common-workflows/dynamic-layout-switching.md
+++ b/docs/common-workflows/dynamic-layout-switching.md
@@ -0,0 +1,37 @@
 # Dynamically Layout Switching
 With `komorebi` it is possible to define rules to automatically change the
 layout on a specified workspace when a threshold of window containers is met.
 ```json
 {
  "monitors": [
    {
      "workspaces": [
        {
          "name": "personal",
          "layout_rules": {
            "1": "BSP"
          }
          "custom_layout_rules": {
            "5": "C:/Users/LGUG2Z/my-custom-layout.json"
          }
        },
      ]
    }
  ]
 }
 ```
 In this example, when there are one or more window containers visible on the
 screen, the BSP layout is used, and when there are five or more window
 containers visible, a custom layout is used.
 However, if you add workspace layout rules, you will not be able to manually
 change the layout of a workspace until all layout rules for that workspace have
 been cleared.
 ```powershell
 # for example, to clear rules from monitor 0, workspace 0
 komorebic clear-workspace-layout-rules 0 0
 ```
--- a/docs/common-workflows/focus-follows-mouse.md
+++ b/docs/common-workflows/focus-follows-mouse.md
@@ -0,0 +1,34 @@
 # Focus Follows Mouse
 `komorebi` supports two focus-follows-mouse implementations; the native Windows
 Xmouse implementation, which treats the desktop, the task bar, and the system
 tray as windows and switches focus to them eagerly, and a custom `komorebi`
 implementation, which only considers windows managed by `komorebi` as valid
 targets to switch focus to when moving the mouse.
 To enable the `komorebi` implementation you must start the process with the
 `--ffm` flag to explicitly enable the feature. This is because the mouse
 tracking required for this feature significantly increases the CPU usage of the
 process (on my machine, it jumps from <1% to ~4~), and this CPU increase
 persists regardless of whether focus-follows-mouse is enabled or disabled at
 any given time via `komorebic`'s configuration commands.
 If the `komorebi` process has been started with the `--ffm` flag, you can
 enable focus follows mouse behaviour in the `komorebi.json` configuration file.
 ```json
 {
  "focus_follows_mouse": "Komorebi"
 }
 ```
 When calling any of the `komorebic` commands related to focus-follows-mouse
 functionality, the `windows` implementation will be chosen as the default
 implementation. You can optionally specify the `komorebi` implementation by
 passing it as an argument to the `--implementation` flag:
 ```powershell
 komorebic.exe toggle-focus-follows-mouse --implementation komorebi
 ```
--- a/docs/common-workflows/force-manage-windows.md
+++ b/docs/common-workflows/force-manage-windows.md
@@ -0,0 +1,21 @@
 # Force Manage Windows
 ❗️**NOTE**: A significant number of force-manage window rules for the most
 common applications are [already generated for
 you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations)
 In some rare cases, a window may not automatically be registered to be managed
 by `komorebi`. You can add rules to enforce this behaviour in the
 `komorebi.json` configuration file.
 ```json
 {
  "manage_rules": [
    {
      "kind": "Title",
      "id": "Media Player",
      "matching_strategy": "Equals"
    }
  ]
 }
 ```
--- a/docs/common-workflows/ignore-windows.md
+++ b/docs/common-workflows/ignore-windows.md
@@ -0,0 +1,21 @@
 # Ignore Windows
 ❗️**NOTE**: A significant number of ignored window rules for the most common
 applications are [already generated for
 you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations)
 Sometimes you will want a specific application to never be tiled, and instead
 float all the time. You can add rules to enforce this behaviour in the
 `komorebi.json` configuration file.
 ```json
 {
  "float_rules": [
    {
      "kind": "Title",
      "id": "Media Player",
      "matching_strategy": "Equals"
    }
  ]
 }
 ```
--- a/docs/common-workflows/komorebi-config-home.md
+++ b/docs/common-workflows/komorebi-config-home.md
@@ -0,0 +1,27 @@
 # `KOMOREBI_CONFIG_HOME`
 If you do not want to keep _komorebi_-related files in your `$Env:USERPROFILE`
 directory, you can specify a custom directory by setting the
 `$Env:KOMOREBI_CONFIG_HOME` environment variable.
 For example, to use the `~/.config/komorebi` directory:
 ```powershell
 # Run this command to make sure that the directory has been created
 mkdir -p ~/.config/komorebi
 # Run this command to open up your PowerShell profile configuration in Notepad
 notepad $PROFILE
 # Add this line (with your login user!) to the bottom of your PowerShell profile configuration
 $Env:KOMOREBI_CONFIG_HOME = 'C:\Users\LGUG2Z\.config\komorebi'
 # Save the changes and then reload the PowerShell profile
 . $PROFILE
 ```
 If you already have configuration files that you wish to keep, move them to the
 `~/.config/komorebi` directory.
 The next time you run `komorebic start`, any files created by or loaded by
 _komorebi_ will be placed or expected to exist in this folder.
--- a/docs/common-workflows/mouse-follows-focus.md
+++ b/docs/common-workflows/mouse-follows-focus.md
@@ -0,0 +1,15 @@
 # Mouse Follows Focus
 By default, the mouse will move to the center of the window when the focus is
 changed in a given direction. This behaviour is know as 'mouse follows focus'.
 This behaviour can be disabled in the `komorebi.json` configuration file.
 ```json
 {
  "mouse_follows_focus": false,
 }
 ```
 <!-- TODO: Record a new video -->
 [![Watch the tutorial video](https://img.youtube.com/vi/LBoyXQiNINc/hqdefault.jpg)](https://www.youtube.com/watch?v=LBoyXQiNINc)
--- a/docs/common-workflows/remove-gaps.md
+++ b/docs/common-workflows/remove-gaps.md
@@ -0,0 +1,17 @@
 # Remove Gaps
 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.
 ```json
 {
  "default_workspace_padding": 0,
  "default_container_padding": 0
 }
 ```
 <!-- TODO: Record a new video -->
 [![Watch the tutorial video](https://img.youtube.com/vi/eGr07mymgWE/hqdefault.jpg)](https://www.youtube.com/watch?v=eGr07mymgWE)
--- a/docs/common-workflows/tray-and-multi-window-applications.md
+++ b/docs/common-workflows/tray-and-multi-window-applications.md
@@ -0,0 +1,23 @@
 # Tray and Multi-Window Applications
 ❗️**NOTE**: A significant number of tray and multi-window application rules for
 the most common applications are [already generated for
 you](https://github.com/LGUG2Z/komorebi/#generating-common-application-specific-configurations)
 If you are experiencing behaviour where closing a window leaves a blank tile,
 but minimizing the same window does not, you have probably enabled a
 'close/minimize to tray' option for that application. You can tell `komorebi`
 to handle this application appropriately by identifying it via the executable
 name or the window class.
 ```json
 {
  "tray_and_multi_window_applications": [
    {
      "kind": "Class",
      "id": "SDL_app",
      "matching_strategy": "Equals"
    }
  ]
 }
 ```
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -50,8 +50,19 @@ nav:
  - Getting started:
    - Installation: installation.md
    - Example configurations: example-configurations.md
-  - Configuration:
+  - Common workflows:
-    - JSONSchema reference: https://komorebi.lgug2z.com/schema
+    - common-workflows/komorebi-config-home.md
    - common-workflows/active-window-border.md
    - common-workflows/remove-gaps.md
    - common-workflows/ignore-windows.md
    - common-workflows/force-manage-windows.md
    - common-workflows/tray-and-multi-window-applications.md
    - common-workflows/focus-follows-mouse.md
    - common-workflows/mouse-follows-focus.md
    - common-workflows/custom-layouts.md
    - common-workflows/dynamic-layout-switching.md
    - common-workflows/autohotkey.md
  - Configuration reference: https://komorebi.lgug2z.com/schema
  - CLI reference:
    - cli/quickstart.md
    - cli/start.md