diff --git a/src/content/docs/guides/upgrades.mdx b/src/content/docs/guides/upgrades.mdx index c130134e..1df7da96 100644 --- a/src/content/docs/guides/upgrades.mdx +++ b/src/content/docs/guides/upgrades.mdx @@ -28,6 +28,13 @@ package manager. + ```bash title="Upgrade komorebi" + brew update + brew upgrade lgug2z/tap/komorebi-for-mac + ``` + + + ```bash title="Upgrade komorebi" brew update brew upgrade lgug2z/tap/komorebi-for-mac-nightly diff --git a/src/content/docs/usage/rules.mdx b/src/content/docs/usage/rules.mdx index c8c83475..16e83233 100644 --- a/src/content/docs/usage/rules.mdx +++ b/src/content/docs/usage/rules.mdx @@ -3,4 +3,163 @@ title: Rules description: Understanding komorebi's rules system --- -TODO +import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro'; +import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro'; +import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; + + + + + + + + + +komorebi has a flexible rules system which aims to allow users to handle any +problematic applications they encounter via configuration rather than requiring +upstream code changes. + +## Matching Rules + +Applications or windows are identified using either simple or composite . + +Simple matching rules use a against a user-provided identifier targeting an . + + + + ```json + { + "kind": "Exe", + "id": "Discord", + "matching_strategy": "Equals" + } + ``` + + + ```json + { + "kind": "Title", + "id": "Cloudflare Dashboard", + "matching_strategy": "Contains" + } + ``` + + + ```json + { + "kind": "Class", + "id": "Ableton Live Window Class", + "matching_strategy": "Equals" + } + ``` + + + +Composite matching rules consist of multiple simple matching rules which must all evaluate to true to identify an application or window. + +```json +[ + { + "kind": "Exe", + "id": "zen.exe", + "matching_strategy": "Equals" + }, + { + "kind": "Title", + "id": "Cloudflare Dashboard", + "matching_strategy": "Contains" + } +] +``` + +## Workspace Rules + + and a are used to identify applications or windows which should be put on a specific workspace. + +```json +{ + "monitors": [ + { + "workspaces": [ + { + "name": "Chat", + "layout": "Columns", + "workspace_rules": [ + { + "kind": "Exe", + "id": "Discord", + "matching_strategy": "Equals" + } + ], + "initial_workspace_rules": [ + { + "kind": "Exe", + "id": "Slack", + "matching_strategy": "Equals" + } + ] + }, + ] + } + ] +} +``` + +Workspace rules will apply all the time, effectively making it impossible to move the identified application or window to another workspace. + +Initial workspace rules will only apply once when the identified application or window is first created, allowing it to be moved to another workspace later. + +Workspace rules (including initial workspace rules) can be enforced in realtime using the command. + + +## Application Handling Rules + +### Ignore Rules + + are used to identify applications or windows which should be completely ignored by komorebi. Ignored applications cannot be targeted by any `komorebic` commands. + +### Floating Applications + + are used to identify applications or windows which should be put on the [floating layer](./usage/layers). + +### Manage Rules + + are used to identify applications or windows which should be forcibly managed. This is typically a nuclear option for extremely uncooperative applications. + + + + + ### Tray and Multi-Window Applications + + are used to identify multi-window applications and applications which minmize to the system tray. + + ### Slow Application Identifier Rules + + are used to identify applications which are slow to send initial event notifications. + + ### Layered Applications + + are used to identify applications have the `WS_EX_LAYERED` extended window style, but should still be managed. + + ### Object Name Change Applications + + are used to identify applications which send `EVENT_OBJECT_NAMECHANGE` on launch. This is very rare, but includes popular applications such as Firefox (and derivatives), as well as JetBrains IDEs. + + ### Slow Applications + + are used to identify applications which are slow to send initial event notifications. + + + + + + ### Tabbed Applications + + are used to identify applications which use native macOS tabs (Finder, Ghostty etc.) - these are identified using their application name. + + ### Titleless Applications + + are used to identify applications which launch without a title - these are identified using their application name. + + +