From e0aa0ac84365647f4a0b1eb076a390641e284c69 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 13 Jan 2024 21:52:27 -0800 Subject: [PATCH] docs(mkdocs): add index and getting started sections --- docs/example-configurations.md | 182 ++++++++++++++++++++++++++++++ docs/getting-started.md | 37 ------ docs/index.md | 31 +++-- docs/install/build-from-source.md | 19 ---- docs/install/scoop.md | 20 ---- docs/install/winget.md | 16 --- docs/installation.md | 113 +++++++++++++++++++ docs/komorebi.example.json | 26 +++++ docs/whkdrc.sample | 63 +++++++++++ mkdocs.yml | 14 ++- 10 files changed, 417 insertions(+), 104 deletions(-) create mode 100644 docs/example-configurations.md delete mode 100644 docs/getting-started.md delete mode 100644 docs/install/build-from-source.md delete mode 100644 docs/install/scoop.md delete mode 100644 docs/install/winget.md create mode 100644 docs/installation.md create mode 100644 docs/komorebi.example.json create mode 100644 docs/whkdrc.sample diff --git a/docs/example-configurations.md b/docs/example-configurations.md new file mode 100644 index 000000000..cc007e9ff --- /dev/null +++ b/docs/example-configurations.md @@ -0,0 +1,182 @@ +`komorebi`, and tiling window managers in general, are very complex pieces of +software. + +In an attempt to reduce some of the initial configuration burden for users who +are looking to try out the software for the first time, example configurations +are provided and updated whenever appropriate. + +## Downloading example configurations + +Run the following command to download example configuration files for +`komorebi` and `whkd`. Pay attention to the output of the command to see where +the example files have been downloaded. For most new users this will be in the +`$Env:USERPROFILE` directory. + +```powershell +komorebic quickstart +``` + +## komorebi.json + +The example window manager configuration sets some sane defaults and provides +five preconfigured workspaces on the primary monitor each with a different +layout. + +```json +{% include "./komorebi.example.json" %} +``` + +### Application-specific configuration + +There is a [community-maintained +repository](https://github.com/LGUG2Z/komorebi-application-specific-configuration) +of "apps behaving badly" that do not conform to Windows application development +guidelines and behave erratically when used with `komorebi` without additional +configuration. + +You can always download the latest version of these configurations by running +`komorebic fetch-asc`. The output of this command will also provide a line that +you can paste into `komorebi.json` to ensure that the window manager looks for +the file in the correction location. + +When installing and running `komorebi` for the first time, the `komorebic +quickstart` command will usually download this file to the `$Env:USERPROFILE` +directory. + +### Padding + +While you can set the workspace padding (the space between the outer edges of +the windows and the bezel of your monitor) and the container padding (the space +between each of the tiled windows) for each workspace independently, you can +also set a default for both of these values that will apply to all workspaces +using `default_workspace_padding` and `default_container_padding`. + +### Active window border + +You may have seen videos and screenshots of people using `komorebi` with a +thick, colourful active window border. You can also enable this by setting +`active_window_border` to `true`. However, please be warned that this feature +is a crude hack trying to compensate for the insistence of Microsoft Windows +design teams to make custom borders with widths that are actually visible to +the user a thing of the past and removing this capability from the Win32 API. + +I know it's buggy, and I know that most of the it sucks, but this is something +you should be bring up with the billion dollar company and not with me, the +solo developer. + +### Border colours + +If you choose to use the active window border, you can set different colours to +give you visual queues when you are focused on a single window, a stack of +windows, or a window that is in monocole mode. + +The example colours given are blue single, green for stack and pink for +monocle. + +### Layouts + +#### BSP + +``` ++-------+-----+ +| | | +| +--+--+ +| | |--| ++-------+--+--+ +``` + +#### Vertical Stack + +``` ++-------+-----+ +| | | +| +-----+ +| | | ++-------+-----+ +``` + +#### Horizontal Stack + +``` ++------+------+ +| | +|------+------+ +| | | ++------+------+ +``` + +#### Columns + +``` ++--+--+--+--+ +| | | | | +| | | | | +| | | | | ++--+--+--+--+ +``` + +#### Rows +If you have a vertical monitor, I recommend using this layout. + +``` ++-----------+ +|-----------| +|-----------| +|-----------| ++-----------+ +``` + +#### Ultrawide Vertical Stack +If you have an ultrawide monitor, I recommend using this layout. + +``` ++-----+-----------+-----+ +| | | | +| | +-----+ +| | | | +| | +-----+ +| | | | ++-----+-----------+-----+ +``` + + +## whkdrc + +`whkd` is a fairly basic piece of software with a simple configuration format: +key bindings go to the left of the, and shell commands go to the right of the +colon. + +Please remember that `whkd` does not support overriding Microsoft's limitations +on hotkey bindings that include the `Windows` key. If this is important to you, +I recommend using [AutoHotKey](https://autohotkey.com) to set up your key +bindings for `komorebic` commands instead. + +``` +{% include "./whkdrc.sample" %} +``` + +### Setting .shell + +There is one special directive at the top of the file, `.shell` which can be +set to either `powershell`, `pwsh` or `cmd`. Which one you use will depend on +which shell you use in your terminal. + +* `powershell` - set this if you are using the version of PowerShell that comes + installed with Windows 10+ (the executable file for this is `powershell.exe`) + +* `pwsh` - set this if you are using PowerShell 7+, which you have installed yourself either through the Windows Store or WinGet (the executable file for this is `pwsh.exe`) + +* `cmd` - set this if you don't want to use PowerShell at all and instead you + want to call commands through the shell used by the old-school Command + Prompt (the executable file for this is `cmd.exe`) + +### Key codes + +Key codes for alphanumeric and arrow keys are just what you would expect. For +punctuation and other keys, please refer to the [Virtual Key +Codes](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes) +reference. + +If you want to use one of those key codes, put them into lower case and remove +the `VK_` prefix. For example, the keycode `VK_OEM_PLUS` becomes `oem_plus` in +the sample configuration above. diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 7af77b00c..000000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -hide: - - navigation ---- -## Installation - -Komorebi is available pre-built to install via -[Scoop](https://scoop.sh/#/apps?q=komorebi) and -[WinGet](https://winget.run/pkg/LGUG2Z/komorebi), and you may also built -it from [source](https://github.com/LGUG2Z/komorebi) if you would prefer. - - - [Scoop](install/scoop.md) - - [WinGet](install/winget.md) - - [Build from source](install/source.md) - -## Getting Example Configurations - -Run the following command to download example configuration files for -`komorebi` and `whkd`. Pay attention to the output of the command to see -where the example files have been downloaded. - -```powershell -komorebic quickstart -``` - -## Starting Komorebi - -Run the following command to start `komorebi` and `whkd` with the example -configurations. - -It is important that you run this command for the first time without -making any modifications to the example configurations to validate that -you have a working installation of both `komorebi` and `whkd`. - -```powershell -komorebic start --whkd -``` diff --git a/docs/index.md b/docs/index.md index 45c1d80c6..33a4e2405 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,26 @@ -# Komorebi - ![screenshot](https://user-images.githubusercontent.com/13164844/184027064-f5a6cec2-2865-4d65-a549-a1f1da589abf.png) -_komorebi_ is a tiling window manager that works as an extension to -Microsoft's [Desktop Window Manager](https://docs.microsoft.com/en-us/windows/win32/dwm/dwm-overview) in Windows 10 and -above. +`komorebi` is a tiling window manager that works as an extension to Microsoft's +[Desktop Window +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 -used with third-party software such as [AutoHotKey](https://github.com/Lexikos/AutoHotkey_L) to set user-defined +`komorebi` allows you to control application windows, virtual workspaces and +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. -Users are free to make such modifications in their own configuration files for _komorebi_, but these will remain -opt-in and off-by-default for the foreseeable future. +`komorebi` aims to make _as few modifications as possible_ to the operating +system and desktop environment by default. Users are free to make such +modifications in their own configuration files for `komorebi`, but these will +always remain opt-in and off-by-default. + +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 on +[GitHub](https://github.com/LGUG2Z/komorebi). + + +There is also a [YouTube +channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg?sub_confirmation=1) +where I share `komorebi` live programming videos and tutorial videos. diff --git a/docs/install/build-from-source.md b/docs/install/build-from-source.md deleted file mode 100644 index a1b08b2ec..000000000 --- a/docs/install/build-from-source.md +++ /dev/null @@ -1,19 +0,0 @@ -## Installing From Source - -First, [install `rustup`](https://rustup.rs/) to get the `rust` compiler installed on your system, and make sure you have installed the [Visual Studio prerequisites](https://rust-lang.github.io/rustup/installation/windows-msvc.html). - -Then clone the git repository. - -```powershell -git clone https://github.com/LGUG2Z/komorebi.git -``` - -Once inside the repository, you will need to build and install three separate binaries. - -```powershell -cargo +stable install --path komorebi --locked -cargo +stable install --path komorebic --locked -cargo +stable install --path komorebic-no-console --locked -``` - -If the binaries have been built and added to your `$PATH` correctly, you should see some output when running `komorebi --help` and `komorebic --help` diff --git a/docs/install/scoop.md b/docs/install/scoop.md deleted file mode 100644 index efc73561f..000000000 --- a/docs/install/scoop.md +++ /dev/null @@ -1,20 +0,0 @@ -## Installing with Scoop - -It highly recommended that you enable support for long paths in Windows by running the following command in an Administrator Terminal before installing komorebi. - -```powershell -Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -``` -### Add the Extras bucket -``` -scoop bucket add extras -``` - -### Install komorebi and whkd - -This command installs `komorebi` and `whkd`. -``` -scoop install komorebi whkd -``` - -Once komorebi is installed, proceed to get the [example configurations](../getting-started.html#getting-example-configurations). diff --git a/docs/install/winget.md b/docs/install/winget.md deleted file mode 100644 index 3c547aaae..000000000 --- a/docs/install/winget.md +++ /dev/null @@ -1,16 +0,0 @@ -## Installing with Scoop - -It highly recommended that you enable support for long paths in Windows by running the following command in an Administrator Terminal before installing komorebi. - -```powershell -Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -``` -### Install komorebi and whkd - -This command installs `komorebi` and `whkd`. -``` -winget install LGUG2Z.komorebi -winget install LGUG2Z.whkd -``` - -Once komorebi is installed, proceed to get the [example configurations](../getting-started.html#getting-example-configurations). diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 000000000..5113411e5 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,113 @@ +# Getting started + +`komorebi` is a tiling window manager for Windows that is comprised comprised +of two main binaries, `komorebi.exe`, which contains the window manager itself, +and `komorebic.exe`, which is the main way to send commands to the tiling +window manager. + +It is important to note that neither `komorebi.exe` or `komorebic.exe` handle +key bindings, because `komorebi` is a tiling window manager and not a hotkey +daemon. + +This getting started guide suggests the installation of +[`whkd`](https://github.com/LGUG2Z/whkd) to allow you to bind `komorebic.exe` +commands to hotkeys to allow you to communicate with the tiling window manager +using keyboard shortcuts. + +However, `whkd` is a very simple hotkey daemon, and notably, does not include +workarounds for Microsoft's restrictions on hotkey combinations that can use +the `Windows` key. + +If using hotkey combinations with the `Windows` key is important to you, I +suggest that once you are familiar with the main `komorebic.exe` commands used +to manipulate the window manager, you use +[AutoHotKey](https://www.autohotkey.com/) to handle your key bindings. + +## Installation + +`komorebi` is available pre-built to install via +[Scoop](https://scoop.sh/#/apps?q=komorebi) and +[WinGet](https://winget.run/pkg/LGUG2Z/komorebi), and you may also built +it from [source](https://github.com/LGUG2Z/komorebi) if you would prefer. + + - [Scoop](install/scoop.md) + - [WinGet](install/winget.md) + - [Build from source](install/source.md) + +## Long path support + +It highly recommended that you enable support for long paths in Windows by +running the following command in an Administrator Terminal before installing +`komorebi`. + +```powershell +Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 +``` + +## Scoop + +Make sure you have installed [`scoop`](https://scoop.sh) and verified that +installed binaries are available in your `$PATH` before proceeding. + +Issues with `komorebi` and related commands not being recognized in the +terminal ultimately come down to the `$PATH` environment variable not being +correctly configured by your package manager and **should not** be raised as +bugs or issues either on the `komorebi` GitHub repository or Discord server. + +### Install komorebi and whkd + +First add the extras bucket + +```powershell +scoop bucket add extras +``` + +Then install the `komorebi` and `whkd` packages using `scoop install` + +```powershell +scoop install komorebi whkd +``` + +Once komorebi is installed, proceed to get the [example +configurations](./example-configurations). + +## WinGet + +Make sure you have installed the latest version of +[`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/) +and verified that installed binaries are available in your `$PATH` before +proceeding. + +Issues with `komorebi` and related commands not being recognized in the +terminal ultimately come down to the `$PATH` environment variable not being +correctly configured by your package manager and **should not** be raised as +bugs or issues either on the `komorebi` GitHub repository or Discord server. + +### Install komorebi and whkd + +Install the `komorebi` and `whkd` packages using `winget install` + +```powershell +winget install LGUG2Z.komorebi +winget install LGUG2Z.whkd +``` + +Once komorebi is installed, proceed to get the [example +configurations](./example-configurations). + +## Building from source + +Make sure you have installed [`rustup`](https://rustup.rs), a stable `rust` +compiler toolchain, and the Visual Studio [Visual Studio +prerequisites](https://rust-lang.github.io/rustup/installation/windows-msvc.html). + +Clone the git repository, enter the directory, and build the following binaries: + +```powershell +cargo +stable install --path komorebi --locked +cargo +stable install --path komorebic --locked +cargo +stable install --path komorebic-no-console --locked +``` + +If the binaries have been built and added to your `$PATH` correctly, you should +see some output when running `komorebi --help` and `komorebic --help` diff --git a/docs/komorebi.example.json b/docs/komorebi.example.json new file mode 100644 index 000000000..1bbc5358a --- /dev/null +++ b/docs/komorebi.example.json @@ -0,0 +1,26 @@ +{ + "$schema": "https://raw.githubusercontent.com/LGUG2Z/komorebi/master/schema.json", + "app_specific_configuration_path": "$Env:USERPROFILE/applications.yaml", + "window_hiding_behaviour": "Cloak", + "cross_monitor_move_behaviour": "Insert", + "alt_focus_hack": true, + "default_workspace_padding": 20, + "default_container_padding": 20, + "active_window_border": false, + "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 } + }, + "monitors": [ + { + "workspaces": [ + { "name": "I", "layout": "BSP" }, + { "name": "II", "layout": "VerticalStack" }, + { "name": "III", "layout": "HorizontalStack" }, + { "name": "IV", "layout": "UltrawideVerticalStack" }, + { "name": "V", "layout": "Rows" } + ] + } + ] +} diff --git a/docs/whkdrc.sample b/docs/whkdrc.sample new file mode 100644 index 000000000..810cf2492 --- /dev/null +++ b/docs/whkdrc.sample @@ -0,0 +1,63 @@ +.shell powershell + +# Reload whkd configuration +# alt + o : taskkill /f /im whkd.exe && start /b whkd # if shell is cmd +alt + o : taskkill /f /im whkd.exe && Start-Process whkd -WindowStyle hidden # if shell is pwsh / powershell +alt + shift + o : komorebic reload-configuration + +# App shortcuts - these require shell to be pwsh / powershell +# The apps will be focused if open, or launched if not open +# alt + f : if ($wshell.AppActivate('Firefox') -eq $False) { start firefox } +# alt + b : if ($wshell.AppActivate('Chrome') -eq $False) { start chrome } + +# Focus windows +alt + h : komorebic focus left +alt + j : komorebic focus down +alt + k : komorebic focus up +alt + l : komorebic focus right +alt + shift + oem_4 : komorebic cycle-focus previous # oem_4 is [ +alt + shift + oem_6 : komorebic cycle-focus next # oem_6 is ] + +# Move windows +alt + shift + h : komorebic move left +alt + shift + j : komorebic move down +alt + shift + k : komorebic move up +alt + shift + l : komorebic move right +alt + shift + return : komorebic promote + +# Stack windows +alt + left : komorebic stack left +alt + down : komorebic stack down +alt + up : komorebic stack up +alt + right : komorebic stack right +alt + oem_1 : komorebic unstack # oem_1 is ; +alt + oem_4 : komorebic cycle-stack previous # oem_4 is [ +alt + oem_6 : komorebic cycle-stack next # oem_6 is ] + +# Resize +alt + oem_plus : komorebic resize-axis horizontal increase +alt + oem_minus : komorebic resize-axis horizontal decrease +alt + shift + oem_plus : komorebic resize-axis vertical increase +alt + shift + oem_minus : komorebic resize-axis vertical decrease + +# Manipulate windows +alt + t : komorebic toggle-float +alt + shift + f : komorebic toggle-monocle + +# Window manager options +alt + shift + r : komorebic retile +alt + p : komorebic toggle-pause + +# Layouts +alt + x : komorebic flip-layout horizontal +alt + y : komorebic flip-layout vertical + +# Workspaces +alt + 1 : komorebic focus-workspace 0 +alt + 2 : komorebic focus-workspace 1 +alt + 3 : komorebic focus-workspace 2 + +# Move windows across workspaces +alt + shift + 1 : komorebic move-to-workspace 0 +alt + shift + 2 : komorebic move-to-workspace 1 +alt + shift + 3 : komorebic move-to-workspace 2 diff --git a/mkdocs.yml b/mkdocs.yml index 6f0c978c1..3a3720823 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,11 +31,21 @@ theme: - content.tabs.link - navigation.footer - navigation.indexes + - navigation.sections - navigation.tabs - - navigation.tabs.sticky - - navigation.tracking - navigation.top + - navigation.tracking - search.highlight - search.share - search.suggest - toc.follow +plugins: + - macros + +nav: + - Komorebi: + - index.md + - Design: design.md + - Getting started: + - Installation: installation.md + - Example configurations: example-configurations.md