feat(docs): add layouts, padding, layers

This commit is contained in:
LGUG2Z committed 2026-02-01 19:37:53 -08:00
1 parent 1f63669b86
commit 26d1e0a348
10 files changed
+329 -51

No files matched your search

+5 -3
View File
@@ -53,9 +53,11 @@ export default defineConfig({
items: [
{ label: "Windows", slug: "usage/windows" },
{ label: "Containers", slug: "usage/containers" },
{ label: "Workspaces", slug: "usage/workspaces" }, // padding, offsets, layouts, layout flips
{ label: "Monitors", slug: "usage/monitors" }, // send-to / move-to, padding, offsets, move behavior
{ label: "Layers", slug: "usage/layers" }, // floating vs tiling layer
{ label: "Workspaces", slug: "usage/workspaces" },
{ label: "Monitors", slug: "usage/monitors" },
{ label: "Layouts", slug: "usage/layouts" },
{ label: "Padding", slug: "usage/padding" },
{ label: "Layers", slug: "usage/layers" },
{ label: "Borders", slug: "usage/borders" }, // borders and colors
{ label: "Themes", slug: "usage/themes" }, // themes for borders (and the bar)
{ label: "Animations", slug: "usage/animations" }, // experimental animations
@@ -0,0 +1,51 @@
---
// src/components/KomorebiConfigPlatformLink.astro
interface Props {
command: string;
text?: string;
}
const { command, text } = Astro.props;
const displayText = text || `${command}`;
---
<a
class="config-platform-link"
data-command={command}
href={`/reference/komorebi-macos/#${command}`}
>{displayText}</a>
<script>
function getPlatform(): string {
const stored = localStorage.getItem('starlight-synced-tabs__platform');
if (!stored) return 'macos';
// Starlight stores as plain string (e.g., "Windows", "macOS")
const label = stored.toLowerCase();
if (label === 'windows' || label === 'win') return 'windows';
return 'macos';
}
function updateLinks() {
const platform = getPlatform();
document.querySelectorAll('.config-platform-link').forEach(link => {
const cmd = link.getAttribute('data-command');
link.setAttribute('href', `/reference/komorebi-${platform}/#${cmd}`);
});
}
// Update on page load
updateLinks();
// Listen for tab changes via storage event (works across tabs too)
window.addEventListener('storage', updateLinks);
// Listen for tab clicks on the same page
document.addEventListener('click', (e) => {
const target = e.target as HTMLElement;
const tab = target.closest('[role="tab"]');
if (tab) {
// Small delay to let Starlight update localStorage
setTimeout(updateLinks, 50);
}
});
</script>
@@ -1,5 +1,5 @@
---
// src/components/PlatformLink.astro
// src/components/KomorebicPlatformLink.astro
interface Props {
command: string;
text?: string;
@@ -9,7 +9,7 @@ const { command, text } = Astro.props;
const displayText = text || `komorebic ${command}`;
---
<a
class="platform-link"
class="command-platform-link"
data-command={command}
href={`/reference/komorebic-macos/#${command}`}
>{displayText}</a>
@@ -27,7 +27,7 @@ const displayText = text || `komorebic ${command}`;
function updateLinks() {
const platform = getPlatform();
document.querySelectorAll('.platform-link').forEach(link => {
document.querySelectorAll('.command-platform-link').forEach(link => {
const cmd = link.getAttribute('data-command');
link.setAttribute('href', `/reference/komorebic-${platform}/#${cmd}`);
});
+7 -7
View File
@@ -3,7 +3,7 @@ title: Containers
description: Manipulating containers
---
import PlatformLink from '../../../components/PlatformLink.astro';
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
@@ -23,26 +23,26 @@ Container stacks can be manipulated in the following ways.
#### Directional Stacking
The focused window can be stacked on top of another window in a relative direction using the <PlatformLink command="stack" /> command.
The focused window can be stacked on top of another window in a relative direction using the <KomorebicPlatformLink command="stack" /> command.
#### Consolidation
All windows on a workspace can be consolidated into a single stack using the <PlatformLink command="stack-all" /> command.
All windows on a workspace can be consolidated into a single stack using the <KomorebicPlatformLink command="stack-all" /> command.
### Focus
The focused window at the top of a container stack can be cycled using the <PlatformLink command="cycle-stack" /> command.
The focused window at the top of a container stack can be cycled using the <KomorebicPlatformLink command="cycle-stack" /> command.
### Unstacking
#### Single Windows
The focused window at the top of a container stack can be popped into an independent container using the <PlatformLink command="unstack" /> command.
The focused window at the top of a container stack can be popped into an independent container using the <KomorebicPlatformLink command="unstack" /> command.
#### All Windows
All windows in a stack can be split into independent containers using the <PlatformLink command="unstack-all" /> command.
All windows in a stack can be split into independent containers using the <KomorebicPlatformLink command="unstack-all" /> command.
## Monocle Containers
A container can be set as the monocle container, hiding all other containers on the workspace, by using the <PlatformLink command="toggle-monocle" /> command. This command is reversible.
A container can be set as the monocle container, hiding all other containers on the workspace, by using the <KomorebicPlatformLink command="toggle-monocle" /> command. This command is reversible.
+28 -1
View File
@@ -3,4 +3,31 @@ title: Layers
description: Understanding workspace layers
---
TODO
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>
komorebi has two distinct workspace layers for tiling and floating windows.
## Layer Selection
Whenever a layer is toggled, the windows associated with that layer will be brought to the foreground.
The layer for the focused workspace can be toggled in realtime using the <KomorebicPlatformLink command="toggle-workspace-layer"/> command.
## Floating Layer Behaviour
The <KomorebiConfigPlatformLink command="floatinglayerbehaviour" text="floating layer behaviour"/> can be set <KomorebiConfigPlatformLink command="monitorconfig-floating_layer_behaviour" text="globally"/>, at the <KomorebiConfigPlatformLink command="monitorconfig-floating_layer_behaviour" text="monitor-level"/> and at the <KomorebiConfigPlatformLink command="workspaceconfig-floating_layer_behaviour" text="workspace-level"/> to determine if new windows opened while the floating layer is active shout float or be tiled.
## Floating Layer Placement
The <KomorebiConfigPlatformLink command="placement" text="floating layer placement"/> is set <KomorebiConfigPlatformLink command="monitorconfig-floating_layer_placement" text="globally"/> and determines where a new window is placed is the floating layer behaviour is set to make new windows float.
+60
View File
@@ -0,0 +1,60 @@
---
title: Layouts
description: Configuring layouts
---
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>
## Layout Selection
<KomorebiConfigPlatformLink command="defaultlayout" text="Layouts"/> are selected using the <KomorebiConfigPlatformLink command="workspaceconfig-layout" text="layout configuration option"/> for each workspace and can be pre-configured as <KomorebiConfigPlatformLink command="workspaceconfig-layout_flip" text="layout_flip" text="flipped on specific axis"/>.
Certain layouts have <KomorebiConfigPlatformLink command="workspaceconfig-layout_options" text="options"/> which adjust how they arrange containers on a workspace.
The layout for the focused workspace switched in realtime using the <KomorebicPlatformLink command="change-layout"/> command.
The layout for the focused workspace can be cycled in realtime using the <KomorebicPlatformLink command="cycle-layout"/> command.
The layout for the a workspace identified by monitor and workspace index can be set in realtime using the <KomorebicPlatformLink command="workspace-layout"/> command.
The layout for the a workspace by name can be set in realtime using the <KomorebicPlatformLink command="named-workspace-layout"/> command.
## Layout Rules
<KomorebiConfigPlatformLink command="workspaceconfig-layout_rules" text="Layout rules"/> are used to automatically change the layout on a specified workspace when a threshold of window containers is met.
```json
{
"monitors": [
{
"workspaces": [
{
"name": "workspace with layout rules",
"layout_rules": {
"1": "BSP",
"4": "UltrawideVerticalStack",
"7": "Grid"
}
}
]
}
]
}
```
In the above example
* When there are between 1 and 3 window containers on the workspace, the BSP layout will be applied
* When there are between 4 and 6 window containers on the workspace, the UltrawideVerticalStack layout will be applied
* 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.
+47 -1
View File
@@ -3,4 +3,50 @@ title: Monitors
description: Configuring monitors
---
TODO
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>
## Focus
Monitors can be focused in the following ways.
### By Index
Monitors can be focused by index using the <KomorebicPlatformLink command="focus-monitor"/> command, or by a mixture of monitor index and workspace index using the <KomorebicPlatformLink command="focus-monitor-workspace"/> command.
### Cycle Direction
Monitors can be focused in a cyclic direction using the <KomorebicPlatformLink command="cycle-monitor" /> command.
### By Cursor
Monitors can be focused by cursor position using the <KomorebicPlatformLink command="focus-monitor-at-cursor"/> command.
## Boundary Behaviour
### Cross Boundary Behaviour
There are two behaviours which can be configured when an action on a window container would cross a monitor boundary:
* <KomorebiConfigPlatformLink command="crossboundarybehaviour" text="Workspace"/> - attempts to perform the action across a workspace boundary on the same monitor
* <KomorebiConfigPlatformLink command="crossboundarybehaviour" text="Monitor"/> - attempts to perform the action across a monitor boundary
### Cross Monitor Move Behaviour
There are three behaviours which can be configured when attempting to move a window across a monitor boundary:
* <KomorebiConfigPlatformLink command="movebehaviour" text="Swap"/> the window container with the window container at the edge of the adjacent monitor
* <KomorebiConfigPlatformLink command="movebehaviour" text="Insert"/> the window container into the focused workspace on the adjacent monitor
* <KomorebiConfigPlatformLink command="movebehaviour" text="NoOp"/> (do nothing) if trying to move a window container in the direction of an adjacent monitor
This behaviour can be changed in realtime using the <KomorebicPlatformLink command="cross-monitor-move-behaviour"/> command.
+101
View File
@@ -0,0 +1,101 @@
---
title: Padding
description: Configuring padding
---
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>
## Workspace Padding
Workspace padding (the padding between the workspace and the screen edges) can be manipulated on three different levels:
* The <KomorebiConfigPlatformLink command="default_workspace_padding" text="default workspace padding"/> which will apply to all workspaces unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="monitorconfig-workspace_padding" text="monitor-level workspace padding"/> which will apply to all workspaces on a monitor unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="workspaceconfig-workspace_padding" text="workspace-level workspace padding"/> which will take priority over all other padding configurations for the specified workspace
The workspace padding on the focused workspace can be adjusted (increased or decreased) in realtime using the <KomorebicPlatformLink command="adjust-workspace-padding"/> command.
The workspace padding on the focused workspace can be set to a specific value in realtime using the <KomorebicPlatformLink command="focused-workspace-padding"/> command.
The workspace padding on for a workspace identified by monitor and workspace index can set to a specific value in realtime using the <KomorebicPlatformLink command="workspace-padding"/> command.
The workspace padding on for a named workspace can set to a specific value in realtime using the <KomorebicPlatformLink command="named-workspace-padding"/> command.
## Container Padding
Container padding (the padding between each container on a workspace) can be manipulated on three different levels:
* The <KomorebiConfigPlatformLink command="default_container_padding" text="default container padding"/> which will apply to all workspaces unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="monitorconfig-container_padding" text="monitor-level container padding"/> which will apply to all workspaces on a monitor unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="workspaceconfig-container_padding" text="workspace-level container padding"/> which will take priority over all other padding configurations for the specified workspace
The container padding on the focused workspace can be adjusted (increased or decreased) in realtime using the <KomorebicPlatformLink command="adjust-container-padding"/> command.
The container padding on the focused workspace can be set to a specific value in realtime using the <KomorebicPlatformLink command="focused-workspace-container-padding"/> command.
The container padding on for a workspace identified by monitor and workspace index can set to a specific value in realtime using the <KomorebicPlatformLink command="container-padding"/> command.
The container padding on for a named workspace can set to a specific value in realtime using the <KomorebicPlatformLink command="named-workspace-container-padding"/> command.
## Offsets
### Work Area Offsets
Work area (the area in which komorebi will manage windows) offsets can be manipulated on three different levels:
* The <KomorebiConfigPlatformLink command="global_work_area_offset" text="global work area offset"/> which will apply to all monitors and workspaces unless explicitly configured otherwise on a monitor or workspace
* The <KomorebiConfigPlatformLink command="monitorconfig-work_area_offset" text="monitor-level work area offset"/> which will apply to workspaces on a monitor unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="workspaceconfig-work_area_offset" text="workspace-level work area offset"/> which will take priority over all other work area offset configurations for the specified workspace
The global work area offset can be set in realtime using the <KomorebicPlatformLink command="global-work-area-offset"/> command.
The monitor work area offset can be set for a monitor identified by monitor index in realtime using the <KomorebicPlatformLink command="monitor-work-area-offset"/> command.
The workspace work area offset can be set for a workspace identified by workspace and monitor index in realtime using the <KomorebicPlatformLink command="workspace-work-area-offset"/> command.
### Dynamic Window-Based Work Area Offsets
Work area offsets can also be dynamically adjusted based on the number of window containers present on a workspace.
This is particularly useful for ultrawide monitors when only a single window container is visible, allowing offsets to be added to the left and right to constrain the work area to the center of the monitor.
These dynamic offsets are set at the <KomorebiConfigPlatformLink command="monitorconfig-window_based_work_area_offset_limit" text="monitor-level"/> and can be disabled individually at the <KomorebiConfigPlatformLink command="workspaceconfig-apply_window_based_work_area_offset" text="workspace-level"/>.
```json
{
"monitors": [
{
"window_based_work_area_offset_limit": 1,
"window_based_work_area_offset": {
"left": 400,
"top": 0,
"right": 800,
"bottom": 0
},
"workspaces": [
{
"name": "workspace which inherits the monitor-level window-based work area offset",
"layout": "BSP",
},
{
"name": "workspace which overrides the monitor-level window-based work area offset",
"layout": "BSP",
"apply_window_based_work_area_offset": false
},
]
}
]
}
```
The work area offset will only be applied when the number of window containers visible on the workspace is less than or equal to the `window_based_work_area_offset_limit`.
+15 -15
View File
@@ -2,7 +2,7 @@
title: Windows
description: Manipulating windows
---
import PlatformLink from '../../../components/PlatformLink.astro';
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
@@ -20,19 +20,19 @@ Windows can be focused in the following ways.
### Relative Direction
Windows can be focused in a relative direction using the <PlatformLink command="focus"/> command.
Windows can be focused in a relative direction using the <KomorebicPlatformLink command="focus"/> command.
### Cycle Direction
Windows can be focused in a cyclic direction using the <PlatformLink command="cycle-focus" /> command.
Windows can be focused in a cyclic direction using the <KomorebicPlatformLink command="cycle-focus" /> command.
### Largest Tile
The window at the largest tile can be focused using the <PlatformLink command="promote-focus" /> command.
The window at the largest tile can be focused using the <KomorebicPlatformLink command="promote-focus" /> command.
### Eager focus
It is possible to attempt to focus the first window on any workspace matching an executable name using the <PlatformLink command="eager-focus" /> command.
It is possible to attempt to focus the first window on any workspace matching an executable name using the <KomorebicPlatformLink command="eager-focus" /> command.
## Movement on a Workspace
@@ -40,15 +40,15 @@ Windows can be moved in the following ways.
### Relative Direction
Windows can be moved in a relative direction using the <PlatformLink command="move"/> command.
Windows can be moved in a relative direction using the <KomorebicPlatformLink command="move"/> command.
### Cycle Direction
Windows can be moved in a cyclic direction using the <PlatformLink command="cycle-move" /> command.
Windows can be moved in a cyclic direction using the <KomorebicPlatformLink command="cycle-move" /> command.
### Largest Tile
Windows can be moved to the largest tile using the <PlatformLink command="promote-swap" /> command. This command is reversible.
Windows can be moved to the largest tile using the <KomorebicPlatformLink command="promote-swap" /> command. This command is reversible.
## Movement Across Workspaces
@@ -59,30 +59,30 @@ The commands covering movement of windows across workspaces in komorebi come in
### By Workspace Index
The focused window can be moved or sent to a workspace on the focused monitor identified by an index using the <PlatformLink command="move-to-workspace"/> and <PlatformLink command="send-to-workspace"/> commands respectively.
The focused window can be moved or sent to a workspace on the focused monitor identified by an index using the <KomorebicPlatformLink command="move-to-workspace"/> and <KomorebicPlatformLink command="send-to-workspace"/> commands respectively.
### Cycle Direction
The focused window can be moved or sent to a workspace on the focused monitor in a cyclic direction using the <PlatformLink command="cycle-move-to-workspace"/> and <PlatformLink command="cycle-send-to-workspace"/> commands respectively.
The focused window can be moved or sent to a workspace on the focused monitor in a cyclic direction using the <KomorebicPlatformLink command="cycle-move-to-workspace"/> and <KomorebicPlatformLink command="cycle-send-to-workspace"/> commands respectively.
### By Monitor and Workspace Index
The focused window can be moved or sent to a workspace on a specific monitor identified by monitor and workspace indicies using the <PlatformLink command="move-to-monitor-workspace"/> and <PlatformLink command="send-to-monitor-workspace"/> commands respectively.
The focused window can be moved or sent to a workspace on a specific monitor identified by monitor and workspace indicies using the <KomorebicPlatformLink command="move-to-monitor-workspace"/> and <KomorebicPlatformLink command="send-to-monitor-workspace"/> commands respectively.
### By Name
The focused window can be moved or sent to a workspace in a monitor-agnostic manner by name using the <PlatformLink command="move-to-named-workspace"/> and <PlatformLink command="send-to-named-workspace"/> commands respectively.
The focused window can be moved or sent to a workspace in a monitor-agnostic manner by name using the <KomorebicPlatformLink command="move-to-named-workspace"/> and <KomorebicPlatformLink command="send-to-named-workspace"/> commands respectively.
### By Last Workspace
The focused window can be moved or sent to a last focused workspace on the focused monitor using the <PlatformLink command="move-to-last-workspace"/> and <PlatformLink command="send-to-last-workspace"/> commands respectively.
The focused window can be moved or sent to a last focused workspace on the focused monitor using the <KomorebicPlatformLink command="move-to-last-workspace"/> and <KomorebicPlatformLink command="send-to-last-workspace"/> commands respectively.
## Movement Across Monitors
### By Monitor Index
The focused window can be moved or sent the focused workspace at a monitor identified by index using the <PlatformLink command="move-to-monitor"/> and <PlatformLink command="send-to-monitor"/> commands respectively.
The focused window can be moved or sent the focused workspace at a monitor identified by index using the <KomorebicPlatformLink command="move-to-monitor"/> and <KomorebicPlatformLink command="send-to-monitor"/> commands respectively.
### Cycle Direction
The focused window can be moved or sent to the focused workspace of a monitor in a cyclic direction using the <PlatformLink command="cycle-move-to-monitor"/> and <PlatformLink command="cycle-send-to-monitor"/> commands respectively.
The focused window can be moved or sent to the focused workspace of a monitor in a cyclic direction using the <KomorebicPlatformLink command="cycle-move-to-monitor"/> and <KomorebicPlatformLink command="cycle-send-to-monitor"/> commands respectively.
+12 -21
View File
@@ -3,7 +3,8 @@ title: Workspaces
description: Configuring workspaces
---
import PlatformLink from '../../../components/PlatformLink.astro';
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
@@ -21,19 +22,23 @@ Workspaces can be focused in the following ways.
### By Index
Workspaces can be focused by index on the focused monitor using the <PlatformLink command="focus-workspace"/> command, or by a mixture of monitor index and workspace index using the <PlatformLink command="focus-monitor-workspace"/> command.
Workspaces can be focused by index on the focused monitor using the <KomorebicPlatformLink command="focus-workspace"/> command, or by a mixture of monitor index and workspace index using the <KomorebicPlatformLink command="focus-monitor-workspace"/> command.
### By Name
Workspaces can be focused in a monitor-agnostic manner by name using the <PlatformLink command="focus-named-workspace"/> command. All of your workspaces should have unique names. If two workspaces have the same name, the first match in the window manager state will be focused.
Workspaces can be focused in a monitor-agnostic manner by name using the <KomorebicPlatformLink command="focus-named-workspace"/> command. All of your workspaces should have unique names. If two workspaces have the same name, the first match in the window manager state will be focused.
### By Last Workspace
### Cycle Direction
The last focused workspace on the focused monitor can be focused using the <PlatformLink command="focus-last-workspace"/> command.
Workspaces can be focused in a cyclic direction using the <KomorebicPlatformLink command="cycle-workspace" /> command.
### Last Workspace
The last focused workspace on the focused monitor can be focused using the <KomorebicPlatformLink command="focus-last-workspace"/> command.
### Across Multiple Monitors
Workspaces can be focused by index across all monitors using the <PlatformLink command="focus-workspaces"/> command. This will focus the same workspace index on all monitors simultaneously, giving the feeling of a workspaces which span all monitors.
Workspaces can be focused by index across all monitors using the <KomorebicPlatformLink command="focus-workspaces"/> command. This will focus the same workspace index on all monitors simultaneously, giving the feeling of a workspaces which span all monitors.
## Movement
@@ -41,18 +46,4 @@ Workspaces can be moved to other monitors in the following ways.
### By Focus and Index
The focused workspace can be moved to a monitor identified by an index using the <PlatformLink command="move-workspace-to-monitor"/> command.
## Layouts
### Layout Rules
TODO
## Padding
### Workspace Padding
### Container Padding
TODO
## Offsets
TODO
The focused workspace can be moved to a monitor identified by an index using the <KomorebicPlatformLink command="move-workspace-to-monitor"/> command.