starred/komorebi
1
0
Fork 0
mirror of https://github.com/LGUG2Z/komorebi.git synced 2026-03-21 08:59:11 +01:00
Code Issues 87 Packages Projects Releases 10 Wiki Activity

docs(mkdocs): add index and getting started sections

Browse Source
This commit is contained in:
LGUG2Z
2024-01-13 21:52:27 -08:00
parent 6f08ec1cb3
commit 9d3e0a01b9
10 changed files with 417 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
docs/example-configurations.md Normal file
View File

@@ -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.

37
docs/getting-started.md
View File

@@ -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
```

31
docs/index.md
View File

@@ -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.

19
docs/install/build-from-source.md
View File

@@ -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`

20
docs/install/scoop.md
View File

@@ -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).

16
docs/install/winget.md
View File

@@ -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).

113
docs/installation.md Normal file
View File

@@ -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`

26
docs/komorebi.example.json Normal file
View File

@@ -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" }
]
}
]
}

63
docs/whkdrc.sample Normal file
View File

@@ -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

14
mkdocs.yml
View File

@@ -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