Provide YAML config by default (#1067)

Whim now creates a YAML config if one doesn't exist during startup. The docs have been updated to reflect that YAML is now the default option. Existing configs are not overwritten.
dalyIsaac · Nov 3, 2024 · 8206b19 · 8206b19
1 parent fe8e309
commit 8206b19
Show file tree

Hide file tree

Showing 37 changed files with 365 additions and 244 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -39,6 +39,27 @@ body:
     validations:
       required: true
 
+  - type: textarea
+    attributes:
+      label: Config
+      description: A `whim.config.yaml` that can be used to reproduce the issue.
+      placeholder: |
+        # yaml-language-server: $schema=WHIM_PATH\plugins\Whim.Yaml\schema.json
+        workspaces:
+          entries:
+            - name: Workspace 1
+            - name: Workspace 2
+            - name: Workspace 3
+            - name: Workspace 4
+
+        layout_engines:
+          entries:
+            - type: tree
+              initial_direction: right
+      render: yaml
+    validations:
+      required: false
+
   - type: textarea
     attributes:
       label: Environment

diff --git a/README.md b/README.md
@@ -1,42 +1,54 @@
-# [Whim](https://dalyisaac.github.io/Whim)
+# [Whim](https://dalyisaac.github.io/Whim) 🪟
 
 <!-- NOTE: This is largely a duplicate of docs/docs/index.md -->
 
-Whim is a hackable, pluggable and scriptable dynamic window manager for Windows 10 and 11, built using WinUI 3, .NET, and C# scripting.
+Whim is a hackable, pluggable and scriptable dynamic window manager for Windows.
 
-![Whim demo](docs/images/demo.gif)
+Whim lets you easily layout your windows in a way that suits your workflow via [keyboard shortcuts](https://dalyisaac.github.io/Whim/configure/core/keybinds.html), dragging windows using your mouse, or plugins including a [command palette](https://dalyisaac.github.io/Whim/configure/plugins/command-palette.html) or [bar](https://dalyisaac.github.io/Whim/configure/plugins/bar.html).
 
-## Installation
+## Key Features ✨
+
+- **Multiple Layout Engines**: Choose from various [layout engines](https://dalyisaac.github.io/Whim/configure/core/layout-engines.html) to suit your workflow.
+- **Simple Configuration**: Use [YAML or JSON](https://dalyisaac.github.io/Whim/configure/yaml-json-configuration.html) for easy setup.
+- **Hackable and Pluggable**: Extend Whim with powerful [C# scripts](https://dalyisaac.github.io/Whim/script/scripting.html).
+- **Workspace Management**: Manage windows efficiently across multiple [workspaces](https://dalyisaac.github.io/Whim/configure/core/workspaces.html).
+- **User-Centric Design**: Full control over your window management.
+
+> All the power to the user!
+
+![Whim demo](docs/images/readme.gif)
+
+## Installation 🛠️
 
 Alpha builds are available on the [releases page](https://github.com/dalyIsaac/Whim/releases) on GitHub. Whim has an [updater plugin](https://dalyisaac.github.io/Whim/docs/plugins/updater.html) to keep you up to date.
 
 Installation via package managers is coming in [dalyIsaac/Whim#792](https://github.com/dalyIsaac/Whim/issues/792).
 
-## Why use Whim?
+## Why use Whim? 🤔
 
 A window manager is responsible for controlling the layout of windows in your desktop environment. Whim is a [dynamic window manager](https://en.wikipedia.org/wiki/Dynamic_window_manager), where windows are arranged according to different layouts.
 
 Whim supports multiple layout engines. Each [workspace](https://dalyisaac.github.io/Whim/docs/customize/workspaces.html) can switch between different layout engines. For example, the `TreeLayoutEngine` allows users to create arbitrary grids of windows during runtime (similar to `i3`), while the `SliceLayoutEngine` fully automates windows placement using a predefined, customizable logic (similar to `Awesome` or `dwm`) . For more, see [Layout Engines](https://dalyisaac.github.io/Whim/docs/customize/layout-engines.html).
 
-Whim is configured using C# scripting - no YAML to be found here. This means you can use the full power of C# to configure Whim. Whim also exposes its API for plugins to use. Accordingly, much of the more custom functionality has been implemented as plugins which users can choose to use or not.
+Whim has a simple configuration system that uses [YAML or JSON](https://dalyisaac.github.io/Whim/configure/yaml-json-configuration.html). Whim also has a [C# scripting system](https://dalyisaac.github.io/Whim/script/scripting.html) for more advanced users. This means you can start out with a simple configuration and gradually add more complex functionality, using the full power of C#. Whim exposes its API for plugins to use. Accordingly, much of the more custom functionality has been implemented as plugins which users can choose to use or not.
 
 Whim works by sitting on top of Windows' own window manager. It listens to window events and moves windows accordingly. Whim does not use Windows' native "virtual" desktops, as they lack the ability to activate "desktops" independently of monitors. Instead, Whim has [workspaces](https://dalyisaac.github.io/Whim/docs/customize/workspaces.html).
 
 To see how Whim compares to other Windows window managers, see [Whim vs. Other Window Managers](https://dalyisaac.github.io/Whim/docs/getting-started/comparison.html).
 
-## Documentation
+## Documentation 📖
 
 You can find the Whim documentation at [dalyisaac.github.io/Whim](https://dalyisaac.github.io/Whim).
 
-## Contributing
+## Contributing 🤝
 
 Whim is an open-source project and contributions are welcome! For more information, see the [Contributing](https://dalyisaac.github.io/Whim/docs/contribute/guide.html) page.
 
-## Community
+## Community 🌐
 
 Whim has a [Discord server](https://discord.gg/gEFq9wr7jb) where you can ask questions, get help, and chat with other users.
 
-## Thanks
+## Thanks 🙏
 
 Whim is heavily inspired by the [workspacer](https://github.com/workspacer/workspacer) project - for more, see the [Inspiration](https://dalyisaac.github.io/Whim/getting-started/inspiration.html) page.
 

diff --git a/docs/_includes/plugins/tree-layout-command-palette.md b/docs/_includes/plugins/tree-layout-command-palette.md
@@ -1,4 +1,4 @@
-## Tree Layout Commands <!-- markdownlint-disable-line MD041 -->
+## Tree Layout Commands<!-- markdownlint-disable-line MD041 -->
 
 | Identifier                                       | Title                                                                               | Keybind            |
 | ------------------------------------------------ | ----------------------------------------------------------------------------------- | ------------------ |

diff --git a/docs/configure/core/layout-engines.md b/docs/configure/core/layout-engines.md
@@ -4,11 +4,12 @@ A "layout engine" or <xref:Whim.ILayoutEngine> in Whim is responsible for arrang
 
 ## Available layout engines
 
-| Engine            | TL;DR                                                                    |
-| ----------------- | ------------------------------------------------------------------------ |
-| [`focus`](#focus) | One window at a time                                                     |
-| [`slice`](#slice) | `Awesome`/`dwm`-style dynamic tiling (primary/stack, multi-column, etc.) |
-| [`tree`](#tree)   | `i3`-style dynamic tiling (arbitrary grids)                              |
+| Engine                  | TL;DR                                                                    |
+| ----------------------- | ------------------------------------------------------------------------ |
+| [`focus`](#focus)       | One window at a time                                                     |
+| [`slice`](#slice)       | `Awesome`/`dwm`-style dynamic tiling (primary/stack, multi-column, etc.) |
+| [`tree`](#tree)         | `i3`-style dynamic tiling (arbitrary grids)                              |
+| [`floating`](#floating) | All windows are free-floating                                            |
 
 ## Example Usage
 
@@ -66,7 +67,7 @@ To reorder windows, calling `whim.core.swap_window_in_direction.(left|right|up|d
 
 Windows which are not focused are minimized to the taskbar.
 
-![Focus demo](../../images/focus-layout-demo.gif)
+![Focus demo](../../images/layout-engines/focus.gif)
 
 ## `slice`
 
@@ -90,6 +91,8 @@ Commands for the `slice` layout engine can be found on the [Slice Layout](../plu
         variant: column
   ```
 
+![Column layout demo](../../images/layout-engines/column.gif)
+
 #### Row Layout
 
 - **Description**: Creates a row layout, where windows are stacked horizontally.
@@ -102,6 +105,8 @@ Commands for the `slice` layout engine can be found on the [Slice Layout](../plu
         variant: row
   ```
 
+![Row layout demo](../../images/layout-engines/row.gif)
+
 #### Primary Stack Layout
 
 - **Description**: Creates a primary stack layout, where the first window takes up half the screen, and the remaining windows are stacked vertically on the other half.
@@ -114,6 +119,8 @@ Commands for the `slice` layout engine can be found on the [Slice Layout](../plu
         variant: primary_stack
   ```
 
+![Primary stack layout demo](../../images/layout-engines/primary-stack.gif)
+
 #### Multi-Column Stack Layout
 
 - **Description**: Creates a multi-column layout with the given number of windows in each column. `[2, 1, 0]` will create a layout with 3 columns, where the first column has 2 windows, the second column has 1 window, and the third column has infinite windows.
@@ -129,6 +136,8 @@ Commands for the `slice` layout engine can be found on the [Slice Layout](../plu
         columns: [2, 1, 0]
   ```
 
+![Multi-column stack layout demo](../../images/layout-engines/multi-column-stack.gif)
+
 #### Secondary Primary Stack Layout
 
 - **Description**: Creates a three-column layout, where the primary column is in the middle, the secondary column is on the left, and the overflow column is on the right. The middle column takes up 50% of the screen, and the left and right columns take up 25%.
@@ -146,7 +155,7 @@ Commands for the `slice` layout engine can be found on the [Slice Layout](../plu
         secondary_capacity: 2
   ```
 
-![Slice demo](../../images/slice-layout-demo.gif)
+![Secondary primary stack demo](../../images/layout-engines/secondary-primary-stack.gif)
 
 ## `tree`
 
@@ -161,15 +170,18 @@ layout_engines:
       initial_direction: right
 ```
 
-![Tree demo](../../images/tree-layout-demo.gif)
+![Tree demo](../../images/layout-engines/tree.gif)
 
 Commands for the `tree` layout engine can be found on the [Tree Layout](../plugins/tree-layout.md#commands) plugin page.
 
-## `FloatingLayoutEngine`
+## `floating`
 
-> [!WARNING]
-> This is not yet supported by the YAML/JSON configuration.
+The `floating` layout engine is a layout that has all windows being free-floating. To have specific windows float within a different layout, see the [Floating Window Plugin](../plugins/floating-window.md).
 
-<xref:Whim.FloatingWindow.FloatingLayoutEngine> is a layout that has all windows being free-floating. To have specific windows float within a different layout, see the [Floating Window Plugin](../plugins/floating-window.md).
+```yaml
+layout_engines:
+  entries:
+    - type: floating
+```
 
-![FloatingLayoutEngine demo](../../images/floating-layout-demo.gif)
+![Floating layout demo](../../images/layout-engines/floating.gif)
diff --git a/docs/configure/core/logging.md b/docs/configure/core/logging.md
diff --git a/docs/configure/core/monitors.md b/docs/configure/core/monitors.md
@@ -1,3 +1,5 @@
 # Monitors
 
+Customization of your monitor setup is not yet available - sticky workspaces are being tracked in [this GitHub issue](https://github.com/dalyIsaac/Whim/issues/660).
+
 👷🏗️🚧
diff --git a/docs/configure/core/styling.md b/docs/configure/core/styling.md
@@ -1,7 +1,5 @@
 # Styling
 
-[!INCLUDE [Styling](../../_includes/core/styling.md)]
-
 ## Backdrops
 
 Different Whim windows can support custom backdrops. They will generally be associated with a `backdrop` key in the YAML/JSON configuration. The following backdrops are available:
@@ -24,3 +22,7 @@ Different Whim windows can support custom backdrops. They will generally be asso
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `type`                 | The type of backdrop to use.                                                                                                                                                 |
 | `always_show_backdrop` | By default, WinUI will disable the backdrop when the window loses focus. Whim overrides this setting. Set this to false to disable the backdrop when the window loses focus. |
+
+## XAML Styling
+
+Loading XAML styles via YAML/JSON is being tracked in [this GitHub issue](https://github.com/dalyIsaac/Whim/issues/1064). In the meantime, it is available [via C# scripting](../../script/core/styling.md).
diff --git a/docs/configure/plugins/overview.md b/docs/configure/plugins/overview.md
@@ -1,17 +1,17 @@
 # Plugins Overview
 
-Whim is build around plugins. Plugins are loaded as required by Whim based on the configuration.
+Whim is built around plugins. They provide additional functionality to Whim, such as a bar, floating windows, or a command palette. Plugins are loaded as required by Whim based on the configuration.
 
-| Plugin                      | TL;DR                                                                                  | Docs                                                        |
-| --------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| Bar                         | Adds a configurable bar to the top of each screen                                      | [`plugins.bar`](bar.md)                                     |
-| Command Palette             | Fuzzy command palette filled with [commands](../core/commands.md)                      | [`plugins.command_palette`](command-palette.md)             |
-| Floating Window             | Lets windows float outside other layout engines                                        | [`plugins.floating_window`](floating-window.md)             |
-| Focus                       | Adds a border around the current window                                                | [`plugins.focus_indicator`](focus-indicator.md)             |
-| Gaps                        | Adds gaps between windows                                                              | [`plugins.gaps`](gaps.md)                                   |
-| Layout Preview              | Shows a preview when dragging windows                                                  | [`plugins.layout_preview`](layout-preview.md)               |
-| Slice Layout                | Plugin for the [`SliceLayoutEngine`](../core/layout-engines.md#slice)                  | [`plugins.slice_layout`](slice-layout.md)                   |
-| Tree Layout                 | Plugin for the [`TreeLayoutEngine`](../core/layout-engines.md#tree)                    | [`plugins.tree_layout`](tree-layout.md)                     |
-| Tree Layout Bar             | Provides a widget for the [Bar](bar.md), for the `TreeLayoutEngine`                    | [`plugins.bar`](bar.md#tree-layout-widget)                  |
-| Tree Layout Command Palette | Adds `TreeLayoutEngine`-specific commands to the [Command Palette](command-palette.md) | [`plugins.command_palette`](command-palette.md#tree-layout) |
-| Updater                     | Plugin to automatically update Whim                                                    | [`plugins.updater`](updater.md)                             |
+| Plugin                      | TL;DR                                                                                  | Docs                                                                 |
+| --------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Bar                         | Adds a configurable bar to the top of each screen                                      | [`plugins.bar`](bar.md)                                              |
+| Command Palette             | Fuzzy command palette filled with [commands](../core/commands.md)                      | [`plugins.command_palette`](command-palette.md)                      |
+| Floating Window             | Lets windows float outside other layout engines                                        | [`plugins.floating_window`](floating-window.md)                      |
+| Focus                       | Adds a border around the current window                                                | [`plugins.focus_indicator`](focus-indicator.md)                      |
+| Gaps                        | Adds gaps between windows                                                              | [`plugins.gaps`](gaps.md)                                            |
+| Layout Preview              | Shows a preview when dragging windows                                                  | [`plugins.layout_preview`](layout-preview.md)                        |
+| Slice Layout                | Plugin for the [`SliceLayoutEngine`](../core/layout-engines.md#slice)                  | [`plugins.slice_layout`](slice-layout.md)                            |
+| Tree Layout                 | Plugin for the [`TreeLayoutEngine`](../core/layout-engines.md#tree)                    | [`plugins.tree_layout`](tree-layout.md)                              |
+| Tree Layout Bar             | Provides a widget for the [Bar](bar.md), for the `TreeLayoutEngine`                    | [`plugins.bar`](bar.md#tree-layout-widget)                           |
+| Tree Layout Command Palette | Adds `TreeLayoutEngine`-specific commands to the [Command Palette](command-palette.md) | [`plugins.command_palette`](command-palette.md#tree-layout-commands) |
+| Updater                     | Plugin to automatically check for updates                                              | [`plugins.updater`](updater.md)                                      |
diff --git a/docs/configure/toc.yml b/docs/configure/toc.yml
@@ -10,7 +10,6 @@ items:
   - href: core/routing.md
   - href: core/filtering.md
   - href: core/styling.md
-  - href: core/logging.md
 
   - name: Plugins
   - href: plugins/overview.md