mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-17 22:33:12 +01:00
feat(docs): add common workflows and layout ratios
This commit is contained in:
1 parent
1d6c56ad7c
commit
f712e25353
10 files changed
+484
No files matched your search
@@ -69,6 +69,10 @@ export default defineConfig({
|
||||
label: "Reference",
|
||||
autogenerate: { directory: "reference" },
|
||||
},
|
||||
{
|
||||
label: "Common Workflows",
|
||||
autogenerate: { directory: "common-workflows" },
|
||||
},
|
||||
],
|
||||
}),
|
||||
],
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 2.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.9 MiB |
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Configuration Directory
|
||||
description: How to set a custom configuration directory
|
||||
---
|
||||
|
||||
You can specify a custom configuration directory by setting the `KOMOREBI_CONFIG_HOME` environment variable.
|
||||
|
||||
If you already have configuration files that you wish to keep, move them to the directory specified by the `KOMOREBI_CONFIG_HOME` environment variable.
|
||||
|
||||
You may reference `$KOMOREBI_CONFIG_HOME` in various options of the configuration when giving file paths, for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"app_specific_configuration_path": "$KOMOREBI_CONFIG_HOME/applications.json"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Ghost Tiles
|
||||
description: How to handle ghost tiles
|
||||
---
|
||||
|
||||
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
|
||||
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
|
||||
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
<Tabs syncKey="platform">
|
||||
<TabItem label="Windows">
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="macOS">
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
Sometimes you may experience an application which leaves "ghost tiles" on a workspace, where there is space reserved for a window but no window visible.
|
||||
|
||||
You will should add [ignore rules](/usage/rules/#ignore-rules) for these windows or applications using information from the <KomorebicPlatformLink command="visible-windows"/> command.
|
||||
|
||||
If you think that the rule you create should be a default rule for everybody, please make a contribution to the [komorebi-application-specific-configuration](https://github.com/LGUG2Z/komorebi-application-specific-configuration) repository.
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Mouse Follows Focus
|
||||
description: How to disable 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,
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,189 @@
|
||||
---
|
||||
title: Multi Monitor Setup
|
||||
description: How to setup komorebi for multiple monitors
|
||||
---
|
||||
|
||||
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
|
||||
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
|
||||
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
<Tabs syncKey="platform">
|
||||
<TabItem label="Windows">
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="macOS">
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
:::note
|
||||
This does not apply to swapping between monitors (i.e. a laptop which either uses only an external display or only the internal display), which is not a multi-monitor workflow, but a complete monitor replacement workflow
|
||||
|
||||
When completely replacing monitors in this way, you should just use a hotkey to restart komorebi: `komorebic stop; sleep 1; komorebic start`
|
||||
:::
|
||||
|
||||
|
||||
## Two Static Monitors
|
||||
|
||||
To set up komorebi to work with multiple monitors, the first step is to add <KomorebiConfigPlatformLink command="monitors" text="independent configurations" /> for each monitor.
|
||||
|
||||
```json
|
||||
{
|
||||
"monitors": [
|
||||
// monitor 1 at arary index 0
|
||||
{
|
||||
"workspaces": [
|
||||
{
|
||||
"name": "Monitor 1, Workspace 1",
|
||||
"layout": "BSP"
|
||||
},
|
||||
{
|
||||
"name": "Monitor 1, Workspace 2",
|
||||
"layout": "VerticalStack"
|
||||
},
|
||||
{
|
||||
"name": "Monitor 1, Workspace 3",
|
||||
"layout": "HorizontalStack"
|
||||
}
|
||||
]
|
||||
},
|
||||
// monitor 2 at array index 1
|
||||
{
|
||||
"workspaces": [
|
||||
{
|
||||
"name": "Monitor 2, Workspace 1",
|
||||
"layout": "BSP"
|
||||
},
|
||||
{
|
||||
"name": "Monitor 2, Workspace 2",
|
||||
"layout": "VerticalStack"
|
||||
},
|
||||
{
|
||||
"name": "Monitor 2, Workspace 3",
|
||||
"layout": "HorizontalStack"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, two monitors are configured. The first monitor is at array index 0, and the second monitor is at array index 1.
|
||||
|
||||
Now if you start komorebi with two monitors connected, the main monitor (as decided by the operating system) will use the configuration at array index 0 and the
|
||||
secondary monitor will use the configuration at array index 1.
|
||||
|
||||
## Assigning Configurations to Specific Monitors
|
||||
|
||||
Let's say there are more monitors, or that you want to make sure a certain configuration is always applied to a certain monitor.
|
||||
|
||||
To do this we have to set our <KomorebiConfigPlatformLink command="display_index_preferences" text="display index preferences" />. The information required to do this can be retrieved using the <KomorebicPlatformLink command="monitor-information" /> command.
|
||||
|
||||
```jsonc
|
||||
// ❯ komorebic monitor-information
|
||||
[
|
||||
{
|
||||
"id": 6620935,
|
||||
"name": "DISPLAY1",
|
||||
"device": "BOE0A1C",
|
||||
"device_id": "BOE0A1C-5&a2bea0b&0&UID512",
|
||||
"serial_number_id": "0",
|
||||
"size": {
|
||||
"left": 0,
|
||||
"top": 0,
|
||||
"right": 1920,
|
||||
"bottom": 1080
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 181932057,
|
||||
"name": "DISPLAY2",
|
||||
"device": "VSC8C31",
|
||||
"device_id": "VSC8C31-5&18560b1f&0&UID4356",
|
||||
"serial_number_id": "UEP174021562",
|
||||
"size": {
|
||||
"left": 0,
|
||||
"top": -1080,
|
||||
"right": 1920,
|
||||
"bottom": 1080
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
In this case the setup is a laptop with a secondary monitor connected.
|
||||
|
||||
Once you know which monitor is which, the `serial_number_id` can be mapped to a specific monitor configuration array index.
|
||||
|
||||
```json
|
||||
{
|
||||
"display_index_preferences": {
|
||||
"0": "0",
|
||||
"1": "UEP174021562"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, the monitor configuration at array index `0` will be mapped to the monitor with the serial number `0`, and the monitor configuration at array index `1` will be mapped to the monitor with the serial number `UEP174021562`.
|
||||
|
||||
## Multiple Monitors in Different Locations
|
||||
|
||||
:::caution
|
||||
You can't use the same config on two different monitors; dedicated configs are required for each monitor
|
||||
:::
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"display_index_preferences": {
|
||||
"0": "HOME_MONITOR_1_ID",
|
||||
"1": "HOME_MONITOR_2_ID",
|
||||
"2": "WORK_MONITOR_1_ID",
|
||||
"3": "WORK_MONITOR_2_ID"
|
||||
},
|
||||
"monitors": [
|
||||
// HOME_MONITOR_1
|
||||
{
|
||||
"workspaces": [
|
||||
// ...
|
||||
]
|
||||
},
|
||||
// HOME_MONITOR_2
|
||||
{
|
||||
"workspaces": [
|
||||
// ...
|
||||
]
|
||||
},
|
||||
// WORK_MONITOR_1
|
||||
{
|
||||
"workspaces": [
|
||||
// ...
|
||||
]
|
||||
},
|
||||
// WORK_MONITOR_2
|
||||
{
|
||||
"workspaces": [
|
||||
// ...
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
In the above example, although you will only ever have 2 monitors connected at any one time, the above configurations will still work in both physical locations.
|
||||
|
||||
## Recommended Display Settings on Microsoft Windows
|
||||
|
||||
In `Settings > System > Display > Multiple Displays`:
|
||||
|
||||
- Disable "Remember windows locations on monitor connection"
|
||||
- Enable "Minimize windows when a monitor is disconnected"
|
||||
|
||||
## Important Workflow Details
|
||||
|
||||
* If you are using a laptop connected to one monitor at work and a different one at home, the work monitor and the home monitor are considered different monitors
|
||||
* When you disconnect from work, komorebi will keep the work monitor cached
|
||||
* You can still use a laptop alone without any monitor and if you need a window that was on the other monitor you can press the taskbar icon or use `alt + tab` to bring it to focus and that window will now be part of the laptop monitor
|
||||
* If you then reconnect the work monitor, the cached version will be applied with all its windows (except any window(s) you might have moved to another monitor)
|
||||
* If however, instead of reconnecting the work monitor, you connect the home monitor, then the work monitor will still remain cached, and komorebi will load the home monitor from the cache (if it exists)
|
||||
* Sometimes when you disconnect/reconnect a monitor the event might be missed by komorebi, meaning that Windows will show you both monitors but komorebi won't know about the existence of one of them
|
||||
* If you notice this type of weird behaviour, always run the <KomorebicPlatformLink command="monitor-information" /> command and validate if one of the monitors is missing
|
||||
* To fix this you can try disconnecting and reconnecting the monitor again, or restarting komorebi
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: Multiple Bar Instances
|
||||
description: How to launch multiple instances of komorebi-bar
|
||||
---
|
||||
|
||||
If you would like to run multiple instances of `komorebi-bar` to target different monitors, it is possible to do so by maintaining multiple `komorebi.bar.json` configuration files and specifying their paths in your configuration file.
|
||||
|
||||
You may also use or `$KOMOREBI_CONFIG_HOME` when specifying the paths.
|
||||
|
||||
```json
|
||||
{
|
||||
"bar_configurations": [
|
||||
"$KOMOREBI_CONFIG_HOME/komorebi.bar.monitor1.json",
|
||||
"$KOMOREBI_CONFIG_HOME/komorebi.bar.monitor2.json"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The main difference between different `komorebi.bar.json` files will be the value of `monitor.index` which is used to target the monitor for each instance of `komorebi-bar`.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: Remove All Gaps
|
||||
description: How to remove all 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 configuration options:
|
||||
|
||||
```json
|
||||
{
|
||||
"default_workspace_padding": 0,
|
||||
"default_container_padding": -1,
|
||||
}
|
||||
```
|
||||
@@ -58,3 +58,211 @@ In the above example
|
||||
* When there are between 7 or more window containers on the workspace, the Grid layout will be applied
|
||||
|
||||
Layout rules can be cleared from a workspace by monitor and workspace index using the <KomorebicPlatformLink command="clear-workspace-layout-rules"/> command, and by workspace name using the <KomorebiConfigPlatformLink command="clear-named-workspace-layout-rules"/> command.
|
||||
|
||||
## Layout Ratios
|
||||
|
||||
<KomorebiConfigPlatformLink command="layoutoptions" text="Layout options" /> can be used to define custom split ratios for various layouts.
|
||||
|
||||
BSP layout with default 50/50 splits
|
||||
|
||||

|
||||
|
||||
BSP layout with `column_ratios: [0.7]` and `row_ratios: [0.6]`:
|
||||
|
||||

|
||||
|
||||
### Example Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"monitors": [
|
||||
{
|
||||
"workspaces": [
|
||||
{
|
||||
"name": "main",
|
||||
"layout_options": {
|
||||
"column_ratios": [0.3, 0.4],
|
||||
"row_ratios": [0.4, 0.3]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can specify up to 5 ratio values (defined by `MAX_RATIOS` constant). Each value should be between 0.1 and 0.9
|
||||
(defined by `MIN_RATIO` and `MAX_RATIO` constants). Values outside this range are automatically clamped.
|
||||
Columns or rows without a specified ratio will share the remaining space equally.
|
||||
|
||||
### Usage by Layout
|
||||
|
||||
| Layout | `column_ratios` | `row_ratios` |
|
||||
|--------|-----------------|--------------|
|
||||
| **Columns** | Width of each column | - |
|
||||
| **Rows** | - | Height of each row |
|
||||
| **Grid** | Width of each column (rows are equal height) | - |
|
||||
| **BSP** | `[0]` as horizontal split ratio | `[0]` as vertical split ratio |
|
||||
| **VerticalStack** | `[0]` as primary column width | Stack row heights |
|
||||
| **RightMainVerticalStack** | `[0]` as primary column width | Stack row heights |
|
||||
| **HorizontalStack** | Stack column widths | `[0]` as primary row height |
|
||||
| **UltrawideVerticalStack** | `[0]` center, `[1]` left column | Tertiary stack row heights |
|
||||
|
||||
### Examples
|
||||
|
||||
#### Columns Layout with Custom Widths
|
||||
|
||||
Create 3 columns with 30%, 40%, and 30% widths:
|
||||
|
||||
```json
|
||||
{
|
||||
"layout_options": {
|
||||
"column_ratios": [0.3, 0.4]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The third column automatically gets the remaining 30%
|
||||
:::
|
||||
|
||||
#### Rows Layout with Custom Heights
|
||||
|
||||
Create 3 rows with 20%, 50%, and 30% heights:
|
||||
|
||||
```json
|
||||
{
|
||||
"layout_options": {
|
||||
"row_ratios": [0.2, 0.5]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The third column automatically gets the remaining 30%
|
||||
:::
|
||||
|
||||
#### Grid Layout with Custom Column Widths
|
||||
|
||||
Grid with custom column widths (rows within each column are always equal height):
|
||||
|
||||
```json
|
||||
{
|
||||
"layout_options": {
|
||||
"column_ratios": [0.4, 0.6]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The Grid layout only supports `column_ratios`. Rows within each column are always divided equally because the number of rows per column varies dynamically based on window count
|
||||
:::
|
||||
|
||||
#### VerticalStack with Custom Ratios
|
||||
|
||||
Primary column takes 60% width, and the stack rows are split 30%/70%:
|
||||
|
||||
```json
|
||||
{
|
||||
"layout_options": {
|
||||
"column_ratios": [0.6],
|
||||
"row_ratios": [0.3]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The second row automatically gets the remaining 70%
|
||||
:::
|
||||
|
||||
#### HorizontalStack with Custom Ratios
|
||||
|
||||
Primary row takes 70% height, and the stack columns are split 40%/60%:
|
||||
|
||||
```json
|
||||
{
|
||||
"layout_options": {
|
||||
"row_ratios": [0.7],
|
||||
"column_ratios": [0.4]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The second column automatically gets the remaining 60%
|
||||
:::
|
||||
|
||||
#### UltrawideVerticalStack with Custom Ratios
|
||||
|
||||
Center column at 50%, left column at 25% (remaining 25% goes to tertiary stack),
|
||||
with tertiary rows split 40%/60%:
|
||||
|
||||
```json
|
||||
{
|
||||
"layout_options": {
|
||||
"column_ratios": [0.5, 0.25],
|
||||
"row_ratios": [0.4]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
The second row automatically gets the remaining 60%
|
||||
:::
|
||||
|
||||
#### BSP Layout with Custom Split Ratios
|
||||
|
||||
Use separate ratios for horizontal (left/right) and vertical (top/bottom) splits:
|
||||
|
||||
```json
|
||||
{
|
||||
"layout_options": {
|
||||
"column_ratios": [0.6],
|
||||
"row_ratios": [0.3]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `column_ratios[0]`: Controls all horizontal splits (left window gets 60%, right gets 40%)
|
||||
- `row_ratios[0]`: Controls all vertical splits (top window gets 30%, bottom gets 70%)
|
||||
|
||||
:::note
|
||||
BSP only uses the first value (`[0]`) from each ratio array. This single ratio is applied consistently to all splits of that type throughout the layout. Additional values in the arrays are ignored
|
||||
:::
|
||||
|
||||
### Progressive Ratio Behavior
|
||||
|
||||
Ratios are applied progressively as windows are added. For example, with `row_ratios: [0.3, 0.5]` in a VerticalStack:
|
||||
|
||||
| Windows in Stack | Row Heights |
|
||||
|------------------|-------------|
|
||||
| 1 | 100% |
|
||||
| 2 | 30%, 70% (remainder) |
|
||||
| 3 | 30%, 50%, 20% (remainder) |
|
||||
| 4 | 30%, 50%, 10%, 10% (remainder split equally) |
|
||||
| 5 | 30%, 50%, 6.67%, 6.67%, 6.67% |
|
||||
|
||||
### Automatic Ratio Truncation
|
||||
|
||||
When ratios sum to 100% (or more), they are automatically truncated at config load time.
|
||||
|
||||
For example, if you configure `column_ratios: [0.4, 0.3, 0.3]` (sums to 100%), the last ratio (0.3) is automatically removed, resulting in effectively `[0.4, 0.3]`. This ensures there's always remaining space for the last window.
|
||||
|
||||
| Configured Ratios | Effective Ratios | Reason |
|
||||
|-------------------|------------------|--------|
|
||||
| `[0.3, 0.4]` | `[0.3, 0.4]` | Sum is 0.7, below 1.0 |
|
||||
| `[0.4, 0.3, 0.3]` | `[0.4, 0.3]` | Sum would be 1.0, last ratio truncated |
|
||||
| `[0.5, 0.5]` | `[0.5]` | Sum would be 1.0, last ratio truncated |
|
||||
| `[0.6, 0.5]` | `[0.6]` | Sum would exceed 1.0, last ratio truncated |
|
||||
|
||||
This ensures the layout always fills 100% of the available space and new windows are never placed outside the visible area.
|
||||
|
||||
### Notes
|
||||
|
||||
- Ratios are clamped between 0.1 and 0.9 (prevents zero-sized windows and ensures space for other windows)
|
||||
- Default ratio is 0.5 (50%) when not specified, except for UltrawideVerticalStack secondary column which defaults to 0.25 (25%)
|
||||
- Ratios are applied **progressively** - a ratio is only used when there are more windows to place after the current one
|
||||
- The **last window always takes the remaining space**, regardless of defined ratios
|
||||
- **Ratios that would sum to 100% or more are automatically truncated** at config load time to ensure there's always space for additional windows
|
||||
- Unspecified ratios default to sharing the remaining space equally
|
||||
- You only need to specify the ratios you want to customize; trailing values can be omitted
|
||||
Reference in new issue
Block a user