From 26d1e0a348f64ffdf047db2dfe5213780ea14a41 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sun, 1 Feb 2026 19:37:53 -0800 Subject: [PATCH] feat(docs): add layouts, padding, layers --- astro.config.mjs | 8 +- .../KomorebiConfigPlatformLink.astro | 51 +++++++++ ...Link.astro => KomorebicPlatformLink.astro} | 6 +- src/content/docs/usage/containers.mdx | 14 +-- src/content/docs/usage/layers.mdx | 29 ++++- src/content/docs/usage/layouts.mdx | 60 +++++++++++ src/content/docs/usage/monitors.mdx | 48 ++++++++- src/content/docs/usage/padding.mdx | 101 ++++++++++++++++++ src/content/docs/usage/windows.mdx | 30 +++--- src/content/docs/usage/workspaces.mdx | 33 +++--- 10 files changed, 329 insertions(+), 51 deletions(-) create mode 100644 src/components/KomorebiConfigPlatformLink.astro rename src/components/{PlatformLink.astro => KomorebicPlatformLink.astro} (89%) create mode 100644 src/content/docs/usage/layouts.mdx create mode 100644 src/content/docs/usage/padding.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 43400f60..b70f75d5 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -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 diff --git a/src/components/KomorebiConfigPlatformLink.astro b/src/components/KomorebiConfigPlatformLink.astro new file mode 100644 index 00000000..587d12c3 --- /dev/null +++ b/src/components/KomorebiConfigPlatformLink.astro @@ -0,0 +1,51 @@ +--- +// src/components/KomorebiConfigPlatformLink.astro +interface Props { + command: string; + text?: string; +} + +const { command, text } = Astro.props; +const displayText = text || `${command}`; +--- +{displayText} + + diff --git a/src/components/PlatformLink.astro b/src/components/KomorebicPlatformLink.astro similarity index 89% rename from src/components/PlatformLink.astro rename to src/components/KomorebicPlatformLink.astro index ac7fa8f4..c325857d 100644 --- a/src/components/PlatformLink.astro +++ b/src/components/KomorebicPlatformLink.astro @@ -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}`; --- {displayText} @@ -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}`); }); diff --git a/src/content/docs/usage/containers.mdx b/src/content/docs/usage/containers.mdx index 57d971ab..1c697dab 100644 --- a/src/content/docs/usage/containers.mdx +++ b/src/content/docs/usage/containers.mdx @@ -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'; @@ -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 command. +The focused window can be stacked on top of another window in a relative direction using the command. #### Consolidation -All windows on a workspace can be consolidated into a single stack using the command. +All windows on a workspace can be consolidated into a single stack using the command. ### Focus -The focused window at the top of a container stack can be cycled using the command. +The focused window at the top of a container stack can be cycled using the command. ### Unstacking #### Single Windows -The focused window at the top of a container stack can be popped into an independent container using the command. +The focused window at the top of a container stack can be popped into an independent container using the command. #### All Windows -All windows in a stack can be split into independent containers using the command. +All windows in a stack can be split into independent containers using the command. ## Monocle Containers -A container can be set as the monocle container, hiding all other containers on the workspace, by using the command. This command is reversible. +A container can be set as the monocle container, hiding all other containers on the workspace, by using the command. This command is reversible. diff --git a/src/content/docs/usage/layers.mdx b/src/content/docs/usage/layers.mdx index ccd24523..13ab65c5 100644 --- a/src/content/docs/usage/layers.mdx +++ b/src/content/docs/usage/layers.mdx @@ -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'; + + + + + + + + + +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 command. + +## Floating Layer Behaviour + +The can be set , at the and at the to determine if new windows opened while the floating layer is active shout float or be tiled. + + +## Floating Layer Placement + +The is set and determines where a new window is placed is the floating layer behaviour is set to make new windows float. diff --git a/src/content/docs/usage/layouts.mdx b/src/content/docs/usage/layouts.mdx new file mode 100644 index 00000000..ed806c1b --- /dev/null +++ b/src/content/docs/usage/layouts.mdx @@ -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'; + + + + + + + + + +## Layout Selection + + are selected using the for each workspace and can be pre-configured as . + +Certain layouts have which adjust how they arrange containers on a workspace. + +The layout for the focused workspace switched in realtime using the command. + +The layout for the focused workspace can be cycled in realtime using the command. + +The layout for the a workspace identified by monitor and workspace index can be set in realtime using the command. + +The layout for the a workspace by name can be set in realtime using the command. + +## 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 command, and by workspace name using the command. diff --git a/src/content/docs/usage/monitors.mdx b/src/content/docs/usage/monitors.mdx index 21f298cf..486dc1b4 100644 --- a/src/content/docs/usage/monitors.mdx +++ b/src/content/docs/usage/monitors.mdx @@ -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'; + + + + + + + + + + +## Focus + +Monitors can be focused in the following ways. + +### By Index + +Monitors can be focused by index using the command, or by a mixture of monitor index and workspace index using the command. + +### Cycle Direction + +Monitors can be focused in a cyclic direction using the command. + +### By Cursor + +Monitors can be focused by cursor position using the 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: + +* - attempts to perform the action across a workspace boundary on the same 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: + +* the window container with the window container at the edge of the adjacent monitor +* the window container into the focused workspace on the adjacent monitor +* (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 command. diff --git a/src/content/docs/usage/padding.mdx b/src/content/docs/usage/padding.mdx new file mode 100644 index 00000000..f95920e8 --- /dev/null +++ b/src/content/docs/usage/padding.mdx @@ -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'; + + + + + + + + + +## Workspace Padding + +Workspace padding (the padding between the workspace and the screen edges) can be manipulated on three different levels: + +* The which will apply to all workspaces unless explicitly configured otherwise on a workspace +* The which will apply to all workspaces on a monitor unless explicitly configured otherwise on a workspace +* The 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 command. + +The workspace padding on the focused workspace can be set to a specific value in realtime using the command. + +The workspace padding on for a workspace identified by monitor and workspace index can set to a specific value in realtime using the command. + +The workspace padding on for a named workspace can set to a specific value in realtime using the command. + +## Container Padding + +Container padding (the padding between each container on a workspace) can be manipulated on three different levels: + +* The which will apply to all workspaces unless explicitly configured otherwise on a workspace +* The which will apply to all workspaces on a monitor unless explicitly configured otherwise on a workspace +* The 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 command. + +The container padding on the focused workspace can be set to a specific value in realtime using the command. + +The container padding on for a workspace identified by monitor and workspace index can set to a specific value in realtime using the command. + +The container padding on for a named workspace can set to a specific value in realtime using the command. + + +## Offsets + +### Work Area Offsets + +Work area (the area in which komorebi will manage windows) offsets can be manipulated on three different levels: + +* The which will apply to all monitors and workspaces unless explicitly configured otherwise on a monitor or workspace +* The which will apply to workspaces on a monitor unless explicitly configured otherwise on a workspace +* The 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 command. +The monitor work area offset can be set for a monitor identified by monitor index in realtime using the command. +The workspace work area offset can be set for a workspace identified by workspace and monitor index in realtime using the 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 and can be disabled individually at the . + +```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`. diff --git a/src/content/docs/usage/windows.mdx b/src/content/docs/usage/windows.mdx index 7dc9700a..37018280 100644 --- a/src/content/docs/usage/windows.mdx +++ b/src/content/docs/usage/windows.mdx @@ -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'; @@ -20,19 +20,19 @@ Windows can be focused in the following ways. ### Relative Direction -Windows can be focused in a relative direction using the command. +Windows can be focused in a relative direction using the command. ### Cycle Direction -Windows can be focused in a cyclic direction using the command. +Windows can be focused in a cyclic direction using the command. ### Largest Tile -The window at the largest tile can be focused using the command. +The window at the largest tile can be focused using the command. ### Eager focus -It is possible to attempt to focus the first window on any workspace matching an executable name using the command. +It is possible to attempt to focus the first window on any workspace matching an executable name using the 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 command. +Windows can be moved in a relative direction using the command. ### Cycle Direction -Windows can be moved in a cyclic direction using the command. +Windows can be moved in a cyclic direction using the command. ### Largest Tile -Windows can be moved to the largest tile using the command. This command is reversible. +Windows can be moved to the largest tile using the 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 and commands respectively. +The focused window can be moved or sent to a workspace on the focused monitor identified by an index using the and 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 and commands respectively. +The focused window can be moved or sent to a workspace on the focused monitor in a cyclic direction using the and 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 and 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 and commands respectively. ### By Name -The focused window can be moved or sent to a workspace in a monitor-agnostic manner by name using the and commands respectively. +The focused window can be moved or sent to a workspace in a monitor-agnostic manner by name using the and commands respectively. ### By Last Workspace -The focused window can be moved or sent to a last focused workspace on the focused monitor using the and commands respectively. +The focused window can be moved or sent to a last focused workspace on the focused monitor using the and 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 and commands respectively. +The focused window can be moved or sent the focused workspace at a monitor identified by index using the and 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 and commands respectively. +The focused window can be moved or sent to the focused workspace of a monitor in a cyclic direction using the and commands respectively. diff --git a/src/content/docs/usage/workspaces.mdx b/src/content/docs/usage/workspaces.mdx index a4c74916..374f81c1 100644 --- a/src/content/docs/usage/workspaces.mdx +++ b/src/content/docs/usage/workspaces.mdx @@ -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'; @@ -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 command, or by a mixture of monitor index and workspace index using the command. +Workspaces can be focused by index on the focused monitor using the command, or by a mixture of monitor index and workspace index using the command. ### By Name -Workspaces can be focused in a monitor-agnostic manner by name using the 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 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 command. +Workspaces can be focused in a cyclic direction using the command. + +### Last Workspace + +The last focused workspace on the focused monitor can be focused using the command. ### Across Multiple Monitors -Workspaces can be focused by index across all monitors using the 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 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 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 command.