diff --git a/astro.config.mjs b/astro.config.mjs
index b70f75d5..cd104c38 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -69,6 +69,10 @@ export default defineConfig({
label: "Reference",
autogenerate: { directory: "reference" },
},
+ {
+ label: "Common Workflows",
+ autogenerate: { directory: "common-workflows" },
+ },
],
}),
],
diff --git a/src/assets/layout-ratios_after.png b/src/assets/layout-ratios_after.png
new file mode 100644
index 00000000..43cbe251
Binary files /dev/null and b/src/assets/layout-ratios_after.png differ
diff --git a/src/assets/layout-ratios_before.png b/src/assets/layout-ratios_before.png
new file mode 100644
index 00000000..23779c9d
Binary files /dev/null and b/src/assets/layout-ratios_before.png differ
diff --git a/src/content/docs/common-workflows/configuration-directory.mdx b/src/content/docs/common-workflows/configuration-directory.mdx
new file mode 100644
index 00000000..f85edf4d
--- /dev/null
+++ b/src/content/docs/common-workflows/configuration-directory.mdx
@@ -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"
+}
+```
diff --git a/src/content/docs/common-workflows/ghost-tiles.mdx b/src/content/docs/common-workflows/ghost-tiles.mdx
new file mode 100644
index 00000000..15657d8a
--- /dev/null
+++ b/src/content/docs/common-workflows/ghost-tiles.mdx
@@ -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';
+
+
+
+
+
+
+
+
+
+
+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 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.
diff --git a/src/content/docs/common-workflows/mouse-follows-focus.mdx b/src/content/docs/common-workflows/mouse-follows-focus.mdx
new file mode 100644
index 00000000..382fe650
--- /dev/null
+++ b/src/content/docs/common-workflows/mouse-follows-focus.mdx
@@ -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,
+}
+```
diff --git a/src/content/docs/common-workflows/multi-monitor-setup.mdx b/src/content/docs/common-workflows/multi-monitor-setup.mdx
new file mode 100644
index 00000000..6106f151
--- /dev/null
+++ b/src/content/docs/common-workflows/multi-monitor-setup.mdx
@@ -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';
+
+
+
+
+
+
+
+
+
+:::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 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 . The information required to do this can be retrieved using the 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 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
diff --git a/src/content/docs/common-workflows/multiple-bar-instances.mdx b/src/content/docs/common-workflows/multiple-bar-instances.mdx
new file mode 100644
index 00000000..3354cc54
--- /dev/null
+++ b/src/content/docs/common-workflows/multiple-bar-instances.mdx
@@ -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`.
diff --git a/src/content/docs/common-workflows/remove-all-gaps.mdx b/src/content/docs/common-workflows/remove-all-gaps.mdx
new file mode 100644
index 00000000..897aebcc
--- /dev/null
+++ b/src/content/docs/common-workflows/remove-all-gaps.mdx
@@ -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,
+}
+```
diff --git a/src/content/docs/usage/layouts.mdx b/src/content/docs/usage/layouts.mdx
index ed806c1b..734c6bea 100644
--- a/src/content/docs/usage/layouts.mdx
+++ b/src/content/docs/usage/layouts.mdx
@@ -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 command, and by workspace name using the command.
+
+## Layout Ratios
+
+ 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