From 4e31f7e047500cb3454359fc05865a5adf156f00 Mon Sep 17 00:00:00 2001
From: Ivan Molodetskikh <yalterz@gmail.com>
Date: Thu, 16 May 2024 12:12:51 +0400
Subject: wiki: Document named workspaces

---
 wiki/Configuration:-Named-Workspaces.md | 36 +++++++++++++++++++++++++++++++++
 wiki/Configuration:-Window-Rules.md     | 18 +++++++++++++++++
 wiki/_Sidebar.md                        |  1 +
 3 files changed, 55 insertions(+)
 create mode 100644 wiki/Configuration:-Named-Workspaces.md

(limited to 'wiki')

diff --git a/wiki/Configuration:-Named-Workspaces.md b/wiki/Configuration:-Named-Workspaces.md
new file mode 100644
index 00000000..e2938655
--- /dev/null
+++ b/wiki/Configuration:-Named-Workspaces.md
@@ -0,0 +1,36 @@
+### Overview
+
+You can declare named workspaces at the top level of the config:
+
+```
+workspace "browser"
+
+workspace "chat" {
+    open-on-output "DP-2"
+}
+```
+
+Contrary to normal dynamic workspaces, named workspaces always exist, even when they have no windows.
+Otherwise, they behave like any other workspace: you can move them around, move to a different monitor, and so on.
+
+Actions like `focus-workspace` or `move-column-to-workspace` can refer to workspaces by name.
+Also, you can use an `open-on-workspace` window rule to make a window open on a specific named workspace:
+
+```
+// Declare a workspace named "chat" that opens on the "DP-2" output.
+workspace "chat" {
+    open-on-output "DP-2"
+}
+
+// Open Telegram on the "chat" workspace at niri startup.
+window-rule {
+    match at-startup=true app-id=r#"^org\.telegram\.desktop$"#
+    open-on-workspace "chat"
+}
+```
+
+Named workspaces initially appear in the order they are declared in the config file.
+When editing the config while niri is running, newly declared named workspaces will appear at the very top of a monitor.
+
+If you delete some named workspace from the config, the workspace will become normal (unnamed), and if there are no windows on it, it will be removed (as any other normal workspace).
+There's no way to give a name to an already existing workspace, but you can simply move windows that you want to a new, empty named workspace.
diff --git a/wiki/Configuration:-Window-Rules.md b/wiki/Configuration:-Window-Rules.md
index f1be4680..d4b50f3b 100644
--- a/wiki/Configuration:-Window-Rules.md
+++ b/wiki/Configuration:-Window-Rules.md
@@ -37,6 +37,7 @@ window-rule {
     // Properties that apply once upon window opening.
     default-column-width { proportion 0.75; }
     open-on-output "eDP-1"
+    open-on-workspace "chat"
     open-maximized true
     open-fullscreen true
 
@@ -234,6 +235,23 @@ window-rule {
 }
 ```
 
+#### `open-on-workspace`
+
+Make the window open on a specific [named workspace](./Configuration:-Named-Workspaces.md).
+
+If such a workspace does not exist, the window will open on the currently focused workspace as usual.
+
+If the window opens on an output that is not currently focused, the window will not be automatically focused.
+
+```
+// Open Telegram on the "chat" workspace.
+window-rule {
+    match app-id=r#"^org\.telegram\.desktop$"#
+
+    open-on-workspace "chat"
+}
+```
+
 #### `open-maximized`
 
 Make the window open as a maximized column.
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
index 846f78a1..5e999194 100644
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -15,6 +15,7 @@
 * [Outputs](./Configuration:-Outputs.md)
 * [Key Bindings](./Configuration:-Key-Bindings.md)
 * [Layout](./Configuration:-Layout.md)
+* [Named Workspaces](./Configuration:-Named-Workspaces.md)
 * [Miscellaneous](./Configuration:-Miscellaneous.md)
 * [Window Rules](./Configuration:-Window-Rules.md)
 * [Animations](./Configuration:-Animations.md)
-- 
cgit