Merge pull request #759 from atheeq-rhxn/sync-docs

feat: add docs and sync with wiki & website

.github/scripts/sync-wiki.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+import json
+import re
+from pathlib import Path
+
+DOCS_DIR = Path("docs")
+WIKI_DIR = Path("wiki-temp")
+
+FRONTMATTER_RE = re.compile(r"\A---\s*\n.*?^---\s*\n", re.DOTALL | re.MULTILINE)
+DOCS_LINK_RE = re.compile(r"\[([^\]]+)\]\(/docs/(?:[^/)]+/)*([^/)#]+)(#[^)]+)?\)")
+
+
+def collect_all_files() -> list[tuple[Path, str]]:
+    files = []
+
+    def from_dir(directory: Path) -> list[Path]:
+        meta = directory / "meta.json"
+        if meta.exists():
+            data = json.loads(meta.read_text())
+            return [directory / f"{p}.md" for p in data.get("pages", []) if (directory / f"{p}.md").exists()]
+        return sorted(directory.glob("*.md"))
+
+    for src in from_dir(DOCS_DIR):
+        files.append((src, "Home" if src.stem == "index" else src.stem))
+
+    for subdir in sorted(DOCS_DIR.iterdir()):
+        if subdir.is_dir():
+            for src in from_dir(subdir):
+                files.append((src, src.stem))
+
+    return files
+
+
+def main() -> None:
+    files = collect_all_files()
+
+    contents = {src: src.read_text() for src, _ in files}
+
+    for src, dest_name in files:
+        text = FRONTMATTER_RE.sub("", contents[src], count=1).lstrip("\n")
+        text = DOCS_LINK_RE.sub(lambda m: f"[{m.group(1)}]({m.group(2)}{m.group(3) or ''})", text)
+        (WIKI_DIR / f"{dest_name}.md").write_text(text)
+
+    lines: list[str] = []
+    current_section = None
+    for src, dest_name in files:
+        section = "General" if src.parent == DOCS_DIR else src.parent.name.replace("-", " ").title()
+        if section != current_section:
+            if current_section is not None:
+                lines.append("")
+            lines.append(f"## {section}\n")
+            current_section = section
+        if dest_name != "Home":
+            title = dest_name.replace("-", " ").replace("_", " ").title()
+            lines.append(f"- [[{dest_name}|{title}]]")
+
+    (WIKI_DIR / "_Sidebar.md").write_text("\n".join(lines))
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/sync-website.yml

@@ -0,0 +1,42 @@
+name: Sync website
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+
+concurrency:
+  group: sync-website
+  cancel-in-progress: true
+
+jobs:
+  sync-website:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          token: ${{ github.token }}
+
+      - name: Checkout website
+        uses: actions/checkout@v4
+        with:
+          repository: mangowm/mangowm.github.io
+          path: website
+          token: ${{ secrets.WEBSITE_SYNC_TOKEN }}
+          fetch-depth: 1
+
+      - name: Sync docs
+        run: |
+          rm -rf website/apps/web/content/docs
+          cp -r docs website/apps/web/content/docs
+
+      - name: Commit and push
+        working-directory: website
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add apps/web/content/docs
+          git diff --staged --quiet || git commit -m "sync from mango @ ${{ github.sha }}"
+          git push

.github/workflows/sync-wiki.yml

@@ -0,0 +1,40 @@
+name: Sync wiki
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+
+concurrency:
+  group: sync-wiki
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  sync-wiki:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Clone wiki
+        run: |
+          git clone --depth 1 \
+            https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.wiki.git \
+            wiki-temp
+
+      - name: Sync docs to wiki
+        run: |
+          find wiki-temp -not -path 'wiki-temp/.git*' -type f -delete
+          python3 .github/scripts/sync-wiki.py
+
+      - name: Commit and push
+        working-directory: wiki-temp
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --staged --quiet || git commit -m "sync from ${{ github.sha }}"
+          git push

docs/bindings/keys.md

@@ -0,0 +1,204 @@
+---
+title: Key Bindings
+description: Define keyboard shortcuts and modes.
+---
+
+## Syntax
+
+Key bindings follow this format:
+
+```ini
+bind[flags]=MODIFIERS,KEY,COMMAND,PARAMETERS
+```
+
+- **Modifiers**: `SUPER`, `CTRL`, `ALT`, `SHIFT`, `NONE` (combine with `+`, e.g. `SUPER+CTRL+ALT`).
+- **Key**: Key name (from `xev` or `wev`) or keycode (e.g., `code:24` for `q`).
+
+> **Info:** `bind` automatically converts keysym to keycode for comparison. This makes it compatible with all keyboard layouts, but the matching may not always be precise. If a key combination doesn't work on your keyboard layout, use a keycode instead (e.g., `code:24` instead of `q`).
+
+### Flags
+
+- `l`: Works even when screen is locked.
+- `s`: Uses keysym instead of keycode to bind.
+- `r`: Triggers on key release instead of press.
+- `p`: Pass key event to client.
+
+**Examples:**
+
+```ini
+bind=SUPER,Q,killclient
+bindl=SUPER,L,spawn,swaylock
+
+# Using keycode instead of key name
+bind=ALT,code:24,killclient
+
+# Combining keycodes for modifiers and keys
+bind=code:64,code:24,killclient
+bind=code:64+code:133,code:24,killclient
+
+# Bind with no modifier
+bind=NONE,XF86MonBrightnessUp,spawn,brightnessctl set +5%
+
+# Bind a modifier key itself as the trigger key
+bind=alt,shift_l,switch_keyboard_layout
+```
+
+## Key Modes (Submaps)
+
+You can divide key bindings into named modes. Rules:
+
+1. Set `keymode=<name>` before a group of `bind` lines — those binds only apply in that mode.
+2. If no `keymode` is set before a bind, it belongs to the `default` mode.
+3. The special `common` keymode applies its binds **across all modes**.
+
+Use `setkeymode` to switch modes, and `mmsg -b` to query the current mode.
+
+```ini
+# Binds in 'common' apply in every mode
+keymode=common
+bind=SUPER,r,reload_config
+
+# Default mode bindings
+keymode=default
+bind=ALT,Return,spawn,foot
+bind=SUPER,F,setkeymode,resize
+
+# 'resize' mode bindings
+keymode=resize
+bind=NONE,Left,resizewin,-10,0
+bind=NONE,Right,resizewin,+10,0
+bind=NONE,Escape,setkeymode,default
+```
+
+### Single Modifier Key Binding
+
+When binding a modifier key itself, use `NONE` for press and the modifier name for release:
+
+```ini
+# Trigger on press of Super key
+bind=none,Super_L,spawn,rofi -show run
+
+# Trigger on release of Super key
+bindr=Super,Super_L,spawn,rofi -show run
+```
+
+## Dispatchers List
+
+### Window Management
+
+| Command | Param | Description |
+| :--- | :--- | :--- |
+| `killclient` | - | Close the focused window. |
+| `togglefloating` | - | Toggle floating state. |
+| `togglefullscreen` | - | Toggle fullscreen. |
+| `togglefakefullscreen` | - | Toggle "fake" fullscreen (remains constrained). |
+| `togglemaximizescreen` | - | Maximize window (keep decoration/bar). |
+| `toggleglobal` | - | Pin window to all tags. |
+| `toggle_render_border` | - | Toggle border rendering. |
+| `centerwin` | - | Center the floating window. |
+| `minimized` | - | Minimize window to scratchpad. |
+| `restore_minimized` | - | Restore window from scratchpad. |
+| `toggle_scratchpad` | - | Toggle scratchpad. |
+| `toggle_named_scratchpad` | `appid,title,cmd` | Toggle named scratchpad. Launches app if not running, otherwise shows/hides it. |
+
+### Focus & Movement
+
+| Command | Param | Description |
+| :--- | :--- | :--- |
+| `focusdir` | `left/right/up/down` | Focus window in direction. |
+| `focusstack` | `next/prev` | Cycle focus within the stack. |
+| `focuslast` | - | Focus the previously active window. |
+| `exchange_client` | `left/right/up/down` | Swap window with neighbor in direction. |
+| `exchange_stack_client` | `next/prev` | Exchange window position in stack. |
+| `zoom` | - | Swap focused window with Master. |
+
+### Tags & Monitors
+
+| Command | Param | Description |
+| :--- | :--- | :--- |
+| `view` | `-1/0/1-9` or `mask [,synctag]` | View tag. `-1` = previous tagset, `0` = all tags, `1-9` = specific tag, mask e.g. `1\|3\|5`. Optional `synctag` (0/1) syncs the action to all monitors. |
+| `viewtoleft` | `[synctag]` | View previous tag. Optional `synctag` (0/1) syncs to all monitors. |
+| `viewtoright` | `[synctag]` | View next tag. Optional `synctag` (0/1) syncs to all monitors. |
+| `viewtoleft_have_client` | `[synctag]` | View left tag and focus client if present. Optional `synctag` (0/1). |
+| `viewtoright_have_client` | `[synctag]` | View right tag and focus client if present. Optional `synctag` (0/1). |
+| `viewcrossmon` | `tag,monitor_spec` | View specified tag on specified monitor. |
+| `tag` | `1-9 [,synctag]` | Move window to tag. Optional `synctag` (0/1) syncs to all monitors. |
+| `tagsilent` | `1-9` | Move window to tag without focusing it. |
+| `tagtoleft` | `[synctag]` | Move window to left tag. Optional `synctag` (0/1). |
+| `tagtoright` | `[synctag]` | Move window to right tag. Optional `synctag` (0/1). |
+| `tagcrossmon` | `tag,monitor_spec` | Move window to specified tag on specified monitor. |
+| `toggletag` | `0-9` | Toggle tag on window (0 means all tags). |
+| `toggleview` | `1-9` | Toggle tag view. |
+| `comboview` | `1-9` | View multi tags pressed simultaneously. |
+| `focusmon` | `left/right/up/down/monitor_spec` | Focus monitor by direction or [monitor spec](/docs/configuration/monitors#monitor-spec-format). |
+| `tagmon` | `left/right/up/down/monitor_spec,[keeptag]` | Move window to monitor by direction or [monitor spec](/docs/configuration/monitors#monitor-spec-format). `keeptag` is 0 or 1. |
+
+### Layouts
+
+| Command | Param | Description |
+| :--- | :--- | :--- |
+| `setlayout` | `name` | Switch to layout (e.g., `scroller`, `tile`). |
+| `switch_layout` | - | Cycle through available layouts. |
+| `incnmaster` | `+1/-1` | Increase/Decrease number of master windows. |
+| `setmfact` | `+0.05` | Increase/Decrease master area size. |
+| `set_proportion` | `float` | Set scroller window proportion (0.0–1.0). |
+| `switch_proportion_preset` | - | Cycle proportion presets of scroller window. |
+| `scroller_stack` | `left/right/up/down` | Move window inside/outside scroller stack by direction. |
+| `incgaps` | `+/-value` | Adjust gap size. |
+| `togglegaps` | - | Toggle gaps. |
+
+### System
+
+| Command | Param | Description |
+| :--- | :--- | :--- |
+| `spawn` | `cmd` | Execute a command. |
+| `spawn_shell` | `cmd` | Execute shell command (supports pipes `\|`). |
+| `spawn_on_empty` | `cmd,tagnumber` | Open command on empty tag. |
+| `reload_config` | - | Hot-reload configuration. |
+| `quit` | - | Exit mangowm. |
+| `toggleoverview` | - | Toggle overview mode. |
+| `create_virtual_output` | - | Create a headless monitor (for VNC/Sunshine). |
+| `destroy_all_virtual_output` | - | Destroy all virtual monitors. |
+| `toggleoverlay` | - | Toggle overlay state for the focused window. |
+| `toggle_trackpad_enable` | - | Toggle trackpad enable. |
+| `setkeymode` | `mode` | Set keymode. |
+| `switch_keyboard_layout` | `[index]` | Switch keyboard layout. Optional index (0, 1, 2...) to switch to specific layout. |
+| `setoption` | `key,value` | Set config option temporarily. |
+| `disable_monitor` | `monitor_spec` | Shutdown monitor. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). |
+| `enable_monitor` | `monitor_spec` | Power on monitor. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). |
+| `toggle_monitor` | `monitor_spec` | Toggle monitor power. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). |
+
+### Media Controls
+
+> **Warning:** Some keyboards don't send standard media keys. Run `wev` and press your key to check the exact key name.
+
+#### Brightness
+
+Requires: `brightnessctl`
+
+```ini
+bind=NONE,XF86MonBrightnessUp,spawn,brightnessctl s +2%
+bind=SHIFT,XF86MonBrightnessUp,spawn,brightnessctl s 100%
+bind=NONE,XF86MonBrightnessDown,spawn,brightnessctl s 2%-
+bind=SHIFT,XF86MonBrightnessDown,spawn,brightnessctl s 1%
+```
+
+#### Volume
+
+Requires: `wpctl` (WirePlumber)
+
+```ini
+bind=NONE,XF86AudioRaiseVolume,spawn,wpctl set-volume @DEFAULT_SINK@ 5%+
+bind=NONE,XF86AudioLowerVolume,spawn,wpctl set-volume @DEFAULT_SINK@ 5%-
+bind=NONE,XF86AudioMute,spawn,wpctl set-mute @DEFAULT_SINK@ toggle
+bind=SHIFT,XF86AudioMute,spawn,wpctl set-mute @DEFAULT_SOURCE@ toggle
+```
+
+### Floating Window Movement
+
+| Command | Param | Description |
+| :--- | :--- | :--- |
+| `smartmovewin` | `left/right/up/down` | Move floating window by snap distance. |
+| `smartresizewin` | `left/right/up/down` | Resize floating window by snap distance. |
+| `movewin` | `(x,y)` | Move floating window. |
+| `resizewin` | `(width,height)` | Resize window. |

docs/bindings/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Bindings & Input",
+	"pages": ["keys", "mouse-gestures"]
+}

docs/bindings/mouse-gestures.md

@@ -0,0 +1,116 @@
+---
+title: Mouse & Gestures
+description: Configure mouse buttons, scrolling, gestures, and lid switches.
+---
+
+## Mouse Bindings
+
+Assign actions to mouse button presses with optional modifier keys.
+
+### Syntax
+
+```ini
+mousebind=MODIFIERS,BUTTON,COMMAND,PARAMETERS
+```
+
+- **Modifiers**: `SUPER`, `CTRL`, `ALT`, `SHIFT`, `NONE`. Combine with `+` (e.g., `SUPER+CTRL`)
+- **Buttons**: `btn_left`, `btn_right`, `btn_middle`, `btn_side`, `btn_extra`, `btn_forward`, `btn_back`, `btn_task`
+
+> **Warning:** When modifiers are set to `NONE`, only `btn_middle` works in normal mode. `btn_left` and `btn_right` only work in overview mode.
+
+### Examples
+
+```ini
+# Window manipulation
+mousebind=SUPER,btn_left,moveresize,curmove
+mousebind=SUPER,btn_right,moveresize,curresize
+mousebind=SUPER+CTRL,btn_right,killclient
+
+# Overview mode (requires NONE modifier)
+mousebind=NONE,btn_left,toggleoverview,-1
+mousebind=NONE,btn_right,killclient,0
+mousebind=NONE,btn_middle,togglemaximizescreen,0
+```
+
+---
+
+## Axis Bindings
+
+Map scroll wheel movements to actions for workspace and window navigation.
+
+### Syntax
+
+```ini
+axisbind=MODIFIERS,DIRECTION,COMMAND,PARAMETERS
+```
+
+- **Direction**: `UP`, `DOWN`, `LEFT`, `RIGHT`
+
+### Examples
+
+```ini
+axisbind=SUPER,UP,viewtoleft_have_client
+axisbind=SUPER,DOWN,viewtoright_have_client
+```
+
+---
+
+## Gesture Bindings
+
+Enable touchpad swipe gestures for navigation and window management.
+
+### Syntax
+
+```ini
+gesturebind=MODIFIERS,DIRECTION,FINGERS,COMMAND,PARAMETERS
+```
+
+- **Direction**: `up`, `down`, `left`, `right`
+- **Fingers**: `3` or `4`
+
+> **Info:** Gestures require proper touchpad configuration. See [Input Devices](/docs/configuration/input) for touchpad settings like `tap_to_click` and `disable_while_typing`.
+
+### Examples
+
+```ini
+# 3-finger: Window focus
+gesturebind=none,left,3,focusdir,left
+gesturebind=none,right,3,focusdir,right
+gesturebind=none,up,3,focusdir,up
+gesturebind=none,down,3,focusdir,down
+
+# 4-finger: Workspace navigation
+gesturebind=none,left,4,viewtoleft_have_client
+gesturebind=none,right,4,viewtoright_have_client
+gesturebind=none,up,4,toggleoverview
+gesturebind=none,down,4,toggleoverview
+```
+
+---
+
+## Switch Bindings
+
+Trigger actions on hardware events like laptop lid open/close.
+
+### Syntax
+
+```ini
+switchbind=FOLD_STATE,COMMAND,PARAMETERS
+```
+
+- **Fold State**: `fold` (lid closed), `unfold` (lid opened)
+
+> **Warning:** Disable system lid handling in `/etc/systemd/logind.conf`:
+>
+> ```ini
+> HandleLidSwitch=ignore
+> HandleLidSwitchExternalPower=ignore
+> HandleLidSwitchDocked=ignore
+> ```
+
+### Examples
+
+```ini
+switchbind=fold,spawn,swaylock -f -c 000000
+switchbind=unfold,spawn,wlr-dpms on
+```

docs/configuration/basics.md

@@ -0,0 +1,87 @@
+---
+title: Basic Configuration
+description: Learn how to configure mangowm files, environment variables, and autostart scripts.
+---
+
+## Configuration File
+
+mangowm uses a simple configuration file format. By default, it looks for a configuration file in `~/.config/mango/`.
+
+1. **Locate Default Config**
+
+   A fallback configuration is provided at `/etc/mango/config.conf`. You can use this as a reference.
+
+2. **Create User Config**
+
+   Copy the default config to your local config directory to start customizing.
+
+   ```bash
+   mkdir -p ~/.config/mango
+   cp /etc/mango/config.conf ~/.config/mango/config.conf
+   ```
+
+3. **Launch with Custom Config (Optional)**
+
+   If you prefer to keep your config elsewhere, you can launch mango with the `-c` flag.
+
+   ```bash
+   mango -c /path/to/your_config.conf
+   ```
+
+### Sub-Configuration
+
+To keep your configuration organized, you can split it into multiple files and include them using the `source` keyword.
+
+```ini
+# Import keybindings from a separate file
+source=~/.config/mango/bind.conf
+
+# Relative paths work too
+source=./theme.conf
+
+# Optional: ignore if file doesn't exist (useful for shared configs)
+source-optional=~/.config/mango/optional.conf
+```
+
+### Validate Configuration
+
+You can check your configuration for errors without starting mangowm:
+
+```bash
+mango -p /path/to/config.conf
+```
+
+Use with `source-optional` for shared configs across different setups.
+
+## Environment Variables
+
+You can define environment variables directly within your config file. These are set before the window manager fully initializes.
+
+> **Warning:** Environment variables defined here will be **reset** every time you reload the configuration.
+
+```ini
+env=GTK_THEME,Adwaita:dark
+env=XCURSOR_SIZE,24
+```
+
+## Autostart
+
+mangowm can automatically run commands or scripts upon startup. There are two modes for execution:
+
+| Command | Behavior | Usage Case |
+| :--- | :--- | :--- |
+| `exec-once` | Runs **only once** when mangowm starts. | Status bars, Wallpapers, Notification daemons |
+| `exec` | Runs **every time** the config is reloaded. | Scripts that need to refresh settings |
+
+### Example Setup
+
+```ini
+# Start the status bar once
+exec-once=waybar
+
+# Set wallpaper
+exec-once=swaybg -i ~/.config/mango/wallpaper/room.png
+
+# Reload a custom script on config change
+exec=bash ~/.config/mango/reload-settings.sh
+```

docs/configuration/input.md

@@ -0,0 +1,150 @@
+---
+title: Input Devices
+description: Configure keyboard layouts, mouse sensitivity, and touchpad gestures.
+---
+
+## Device Configuration
+
+mangowm provides granular control over different input devices.
+
+### Keyboard Settings
+
+Control key repeat rates and layout rules.
+
+| Setting | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `repeat_rate` | `int` | `25` | How many times a key repeats per second. |
+| `repeat_delay` | `int` | `600` | Delay (ms) before a held key starts repeating. |
+| `numlockon` | `0` or `1` | `0` | Enable NumLock on startup. |
+| `xkb_rules_rules` | `string` | - | XKB rules file (e.g., `evdev`, `base`). Usually auto-detected. |
+| `xkb_rules_model` | `string` | - | Keyboard model (e.g., `pc104`, `macbook`). |
+| `xkb_rules_layout` | `string` | - | Keyboard layout code (e.g., `us`, `de`, `us,de`). |
+| `xkb_rules_variant` | `string` | - | Layout variant (e.g., `dvorak`, `colemak`, `intl`). |
+| `xkb_rules_options` | `string` | - | XKB options (e.g., `caps:escape`, `ctrl:nocaps`). |
+
+**Example:**
+
+```ini
+repeat_rate=40
+repeat_delay=300
+numlockon=1
+xkb_rules_layout=us,de
+xkb_rules_variant=dvorak
+xkb_rules_options=caps:escape,ctrl:nocaps
+```
+
+---
+
+### Trackpad Settings
+
+Specific settings for laptop touchpads. Some settings may require a relogin to take effect.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `disable_trackpad` | `0` | Set to `1` to disable the trackpad entirely. |
+| `tap_to_click` | `1` | Tap to trigger a left click. |
+| `tap_and_drag` | `1` | Tap and hold to drag items. |
+| `trackpad_natural_scrolling` | `0` | Invert scrolling direction (natural scrolling). |
+| `scroll_method` | `1` | `1` (Two-finger), `2` (Edge), `4` (Button). |
+| `click_method` | `1` | `1` (Button areas), `2` (Clickfinger). |
+| `drag_lock` | `1` | Lock dragging after tapping. |
+| `disable_while_typing` | `1` | Disable trackpad while typing. |
+| `left_handed` | `0` | Swap left/right buttons. |
+| `middle_button_emulation` | `0` | Emulate middle button. |
+| `swipe_min_threshold` | `1` | Minimum swipe threshold. |
+
+---
+
+**Detailed descriptions:**
+
+- `scroll_method` values:
+  - `0` — Never send scroll events (no scrolling).
+  - `1` — Two-finger scrolling: send scroll events when two fingers are logically down on the device.
+  - `2` — Edge scrolling: send scroll events when a finger moves along the bottom or right edge.
+  - `4` — Button scrolling: send scroll events when a button is held and the device moves along a scroll axis.
+
+- `click_method` values:
+  - `0` — No software click emulation.
+  - `1` — Button areas: use software-defined areas on the touchpad to generate button events.
+  - `2` — Clickfinger: the number of fingers determines which button is pressed.
+
+- `accel_profile` values:
+  - `0` — No acceleration.
+  - `1` — Flat: no dynamic acceleration. Pointer speed = original input speed × (1 + `accel_speed`).
+  - `2` — Adaptive: slow movement results in less acceleration, fast movement results in more.
+
+- `button_map` values:
+  - `0` — 1/2/3 finger tap maps to left / right / middle.
+  - `1` — 1/2/3 finger tap maps to left / middle / right.
+
+- `send_events_mode` values:
+  - `0` — Send events from this device normally.
+  - `1` — Do not send events from this device.
+  - `2` — Disable this device when an external pointer device is plugged in.
+
+---
+
+### Mouse Settings
+
+Configuration for external mice.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `mouse_natural_scrolling` | `0` | Invert scrolling direction. |
+| `accel_profile` | `2` | `0` (None), `1` (Flat), `2` (Adaptive). |
+| `accel_speed` | `0.0` | Speed adjustment (-1.0 to 1.0). |
+| `left_handed` | `0` | Swap left and right buttons. |
+| `middle_button_emulation` | `0` | Emulate middle button. |
+| `swipe_min_threshold` | `1` | Minimum swipe threshold. |
+| `send_events_mode` | `0` | `0` (Enabled), `1` (Disabled), `2` (Disabled on external mouse). |
+| `button_map` | `0` | `0` (Left/right/middle), `1` (Left/middle/right). |
+
+---
+
+---
+
+## Keyboard Layout Switching
+
+To bind multiple layouts and toggle between them, define the layouts in `xkb_rules_layout` and use `xkb_rules_options` to set a toggle key combination. Then bind `switch_keyboard_layout` to trigger a switch.
+
+```ini
+# Define two layouts: US QWERTY and US Dvorak
+xkb_rules_layout=us,us
+xkb_rules_variant=,dvorak
+xkb_rules_options=grp:lalt_lshift_toggle
+```
+
+Or bind it manually to a key:
+
+```ini
+# Bind Alt+Shift_L to cycle keyboard layout
+bind=alt,shift_l,switch_keyboard_layout
+```
+
+Use `mmsg -g -k` to query the current keyboard layout at any time.
+
+---
+
+## Input Method Editor (IME)
+
+To use Fcitx5 or IBus, set these environment variables in your config file.
+
+> **Info:** These settings require a restart of the window manager to take effect.
+
+**For Fcitx5:**
+
+```ini
+env=GTK_IM_MODULE,fcitx
+env=QT_IM_MODULE,fcitx
+env=SDL_IM_MODULE,fcitx
+env=XMODIFIERS,@im=fcitx
+env=GLFW_IM_MODULE,ibus
+```
+
+**For IBus:**
+
+```ini
+env=GTK_IM_MODULE,ibus
+env=QT_IM_MODULE,ibus
+env=XMODIFIERS,@im=ibus
+```

docs/configuration/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Configuration",
+	"pages": ["basics", "monitors", "input", "xdg-portals", "miscellaneous"]
+}

docs/configuration/miscellaneous.md

@@ -0,0 +1,51 @@
+---
+title: Miscellaneous
+description: Advanced settings for XWayland, focus behavior, and system integration.
+---
+
+## System & Hardware
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `xwayland_persistence` | `1` | Keep XWayland running even when no X11 apps are open (reduces startup lag). |
+| `syncobj_enable` | `0` | Enable `drm_syncobj` timeline support (helps with gaming stutter/lag). **Requires restart.** |
+| `allow_lock_transparent` | `0` | Allow the lock screen to be transparent. |
+| `allow_shortcuts_inhibit` | `1` | Allow shortcuts to be inhibited by clients. |
+| `vrr` | - | Set via [monitor rule](/docs/configuration/monitors#monitor-rules). |
+
+## Focus & Input
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `focus_on_activate` | `1` | Automatically focus windows when they request activation. |
+| `sloppyfocus` | `1` | Focus follows the mouse cursor. |
+| `warpcursor` | `1` | Warp the cursor to the center of the window when focus changes via keyboard. |
+| `cursor_hide_timeout` | `0` | Hide the cursor after `N` seconds of inactivity (`0` to disable). |
+| `drag_tile_to_tile` | `0` | Allow dragging a tiled window onto another to swap their positions. |
+| `drag_corner` | `3` | Corner for drag-to-tile detection (0: none, 1–3: corners, 4: auto-detect). |
+| `drag_warp_cursor` | `1` | Warp cursor when dragging windows to tile. |
+| `axis_bind_apply_timeout` | `100` | Timeout (ms) for detecting consecutive scroll events for axis bindings. |
+| `axis_scroll_factor` | `1.0` | Scroll factor for axis scroll speed (0.1–10.0). |
+
+## Multi-Monitor & Tags
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `focus_cross_monitor` | `0` | Allow directional focus to cross monitor boundaries. |
+| `exchange_cross_monitor` | `0` | Allow exchanging clients across monitor boundaries. |
+| `focus_cross_tag` | `0` | Allow directional focus to cross into other tags. |
+| `view_current_to_back` | `0` | Toggling the current tag switches back to the previously viewed tag. |
+| `scratchpad_cross_monitor` | `0` | Share the scratchpad pool across all monitors. |
+| `single_scratchpad` | `1` | Only allow one scratchpad (named or standard) to be visible at a time. |
+| `circle_layout` | - | A comma-separated list of layouts `switch_layout` cycles through. |
+
+## Window Behavior
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `enable_floating_snap` | `0` | Snap floating windows to edges or other windows. |
+| `snap_distance` | `30` | Max distance (pixels) to trigger floating snap. |
+| `no_border_when_single` | `0` | Remove window borders when only one window is visible on the tag. |
+| `idleinhibit_ignore_visible` | `0` | Allow invisible clients (e.g., background audio players) to inhibit idle. |
+| `drag_tile_refresh_interval` | `8.0` | Interval (1.0–16.0) to refresh tiled window resize during drag. Too small may cause application lag. |
+| `drag_floating_refresh_interval` | `8.0` | Interval (1.0–16.0) to refresh floating window resize during drag. Too small may cause application lag. |

docs/configuration/monitors.md

@@ -0,0 +1,274 @@
+---
+title: Monitors
+description: Manage display outputs, resolution, scaling, and tearing.
+---
+
+## Monitor Rules
+
+You can configure each display output individually using the `monitorrule` keyword.
+
+**Syntax:**
+
+```ini
+monitorrule=name:Values,Parameter:Values,Parameter:Values
+```
+
+> **Info:** If any of the matching fields (`name`, `make`, `model`, `serial`) are set, **all** of the set ones must match to be considered a match. Use `wlr-randr` to get your monitor's name, make, model, and serial.
+
+### Parameters
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | string | Any | Match by monitor name (supports regex) |
+| `make` | string | Any | Match by monitor manufacturer |
+| `model` | string | Any | Match by monitor model |
+| `serial` | string | Any | Match by monitor serial number |
+| `width` | integer | 0-9999 | Monitor width |
+| `height` | integer | 0-9999 | Monitor height |
+| `refresh` | float | 0.001-9999.0 | Monitor refresh rate |
+| `x` | integer | 0-99999 | X position |
+| `y` | integer | 0-99999 | Y position |
+| `scale` | float | 0.01-100.0 | Monitor scale |
+| `vrr` | integer | 0, 1 | Enable variable refresh rate |
+| `rr` | integer | 0-7 | Monitor transform |
+| `custom` | integer | 0, 1 | Enable custom mode (not supported on all displays — may cause black screen) |
+
+### Transform Values
+
+| Value | Rotation |
+| :--- | :--- |
+| `0` | No transform |
+| `1` | 90° counter-clockwise |
+| `2` | 180° counter-clockwise |
+| `3` | 270° counter-clockwise |
+| `4` | 180° vertical flip |
+| `5` | Flip + 90° counter-clockwise |
+| `6` | Flip + 180° counter-clockwise |
+| `7` | Flip + 270° counter-clockwise |
+
+> **Critical:** If you use XWayland applications, **never use negative coordinates** for your monitor positions. This is a known XWayland bug that causes click events to malfunction. Always arrange your monitors starting from `0,0` and extend into positive coordinates.
+
+### Examples
+
+```ini
+# Laptop display: 1080p, 60Hz, positioned at origin
+monitorrule=name:eDP-1,width:1920,height:1080,refresh:60,x:0,y:10
+
+# Match by make and model instead of name
+monitorrule=make:Chimei Innolux Corporation,model:0x15F5,width:1920,height:1080,refresh:60,x:0,y:0
+
+# Virtual monitor with pattern matching
+monitorrule=name:HEADLESS-.*,width:1920,height:1080,refresh:60,x:1926,y:0,scale:1,rr:0,vrr:0
+```
+
+---
+
+## Monitor Spec Format
+
+Several commands (`focusmon`, `tagmon`, `disable_monitor`, `enable_monitor`, `toggle_monitor`, `viewcrossmon`, `tagcrossmon`) accept a **monitor_spec** string to identify a monitor.
+
+**Format:**
+
+```text
+name:xxx&&make:xxx&&model:xxx&&serial:xxx
+```
+
+- Any field can be omitted and there is no order requirement.
+- If all fields are omitted, the string is treated as the monitor name directly (e.g., `eDP-1`).
+- Use `wlr-randr` to find your monitor's name, make, model, and serial.
+
+**Examples:**
+
+```bash
+# By name (shorthand)
+mmsg -d toggle_monitor,eDP-1
+
+# By make and model
+mmsg -d toggle_monitor,make:Chimei Innolux Corporation&&model:0x15F5
+
+# By serial
+mmsg -d toggle_monitor,serial:12345678
+```
+
+---
+
+## Tearing (Game Mode)
+
+Tearing allows games to bypass the compositor's VSync for lower latency.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `allow_tearing` | `0` | Global tearing control: `0` (Disable), `1` (Enable), `2` (Fullscreen only). |
+
+### Configuration
+
+**Enable Globally:**
+
+```ini
+allow_tearing=1
+```
+
+**Enable per Window:**
+
+Use a window rule to force tearing for specific games.
+
+```ini
+windowrule=force_tearing:1,title:vkcube
+```
+
+### Tearing Behavior Matrix
+
+| `force_tearing` \ `allow_tearing` | DISABLED (0) | ENABLED (1) | FULLSCREEN_ONLY (2) |
+| :--- | :--- | :--- | :--- |
+| **UNSPECIFIED** (0) | Not Allowed | Follows tearing_hint | Only fullscreen follows tearing_hint |
+| **ENABLED** (1) | Not Allowed | Allowed | Only fullscreen allowed |
+| **DISABLED** (2) | Not Allowed | Not Allowed | Not Allowed |
+
+### Graphics Card Compatibility
+
+> **Warning:** Some graphics cards require setting the `WLR_DRM_NO_ATOMIC` environment variable before mango starts to successfully enable tearing.
+
+Add this to `/etc/environment` and reboot:
+
+```bash
+WLR_DRM_NO_ATOMIC=1
+```
+
+Or run mango with the environment variable:
+
+```bash
+WLR_DRM_NO_ATOMIC=1 mango
+```
+
+---
+
+## GPU Compatibility
+
+If mango cannot display correctly or shows a black screen, try selecting a specific GPU:
+
+```bash
+# Use a single GPU
+WLR_DRM_DEVICES=/dev/dri/card1 mango
+
+# Use multiple GPUs
+WLR_DRM_DEVICES=/dev/dri/card0:/dev/dri/card1 mango
+```
+
+Some GPUs have compatibility issues with `syncobj_enable=1` — it may crash apps like `kitty` that use syncobj. Set `WLR_DRM_NO_ATOMIC=1` in `/etc/environment` and reboot to resolve this.
+
+---
+
+## Power Management
+
+You can control monitor power using the `mmsg` IPC tool.
+
+```bash
+# Turn off
+mmsg -d disable_monitor,eDP-1
+
+# Turn on
+mmsg -d enable_monitor,eDP-1
+
+# Toggle
+mmsg -d toggle_monitor,eDP-1
+```
+
+You can also use `wlr-randr` for monitor management:
+
+```bash
+# Turn off monitor
+wlr-randr --output eDP-1 --off
+
+# Turn on monitor
+wlr-randr --output eDP-1 --on
+
+# Show all monitors
+wlr-randr
+```
+
+---
+
+## Screen Scale
+
+### Without Global Scale (Recommended)
+
+- If you do not use XWayland apps, you can use monitor rules or `wlr-randr` to set a global monitor scale.
+- If you are using XWayland apps, it is not recommended to set a global monitor scale.
+
+You can set scale like this, for example with a 1.4 factor.
+
+**Dependencies:**
+
+```bash
+yay -S xorg-xrdb
+yay -S xwayland-satellite
+```
+
+**In config file:**
+
+```ini
+env=QT_AUTO_SCREEN_SCALE_FACTOR,1
+env=QT_WAYLAND_FORCE_DPI,140
+```
+
+**In autostart:**
+
+```bash
+echo "Xft.dpi: 140" | xrdb -merge
+gsettings set org.gnome.desktop.interface text-scaling-factor 1.4
+```
+
+**Edit autostart for XWayland:**
+
+```bash
+# Start xwayland
+/usr/sbin/xwayland-satellite :11 &
+# Apply scale 1.4 for xwayland
+sleep 0.5s && echo "Xft.dpi: 140" | xrdb -merge
+```
+
+### Using xwayland-satellite to Prevent Blurry XWayland Apps
+
+If you use fractional scaling, you can use `xwayland-satellite` to automatically scale XWayland apps to prevent blurriness, for example with a scale of 1.4.
+
+**Dependencies:**
+
+```bash
+yay -S xwayland-satellite
+```
+
+**In config file:**
+
+```ini
+env=DISPLAY,:2
+exec=xwayland-satellite :2
+monitorrule=name:eDP-1,width:1920,height:1080,refresh:60,x:0,y:0,scale:1.4,vrr:0,rr:0
+```
+
+> **Warning:** Use a `DISPLAY` value other than `:1` to avoid conflicting with mangowm.
+
+---
+
+## Virtual Monitors
+
+You can create and manage virtual displays through IPC commands:
+
+```bash
+# Create virtual output
+mmsg -d create_virtual_output
+
+# Destroy all virtual outputs
+mmsg -d destroy_all_virtual_output
+```
+
+You can configure virtual monitors using `wlr-randr`:
+
+```bash
+# Show all monitors
+wlr-randr
+
+# Configure virtual monitor
+wlr-randr --output HEADLESS-1 --pos 1921,0 --scale 1 --custom-mode 1920x1080@60Hz
+```
+
+Virtual monitors can be used for screen sharing with tools like [Sunshine](https://github.com/LizardByte/Sunshine) and [Moonlight](https://github.com/moonlight-stream/moonlight-android), allowing other devices to act as extended monitors.

docs/configuration/xdg-portals.md

@@ -0,0 +1,76 @@
+---
+title: XDG Portals
+description: Set up screen sharing, clipboard, keyring, and file pickers using XDG portals.
+---
+
+## Portal Configuration
+
+You can customize portal settings via the following paths:
+
+- **User Configuration (Priority):** `~/.config/xdg-desktop-portal/mango-portals.conf`
+- **System Fallback:** `/usr/share/xdg-desktop-portal/mango-portals.conf`
+
+> **Warning:** If you previously added `dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=wlroots` to your config, remove it. Mango now handles this automatically.
+
+## Screen Sharing
+
+To enable screen sharing (OBS, Discord, WebRTC), you need `xdg-desktop-portal-wlr`.
+
+1. **Install Dependencies**
+
+   `pipewire`, `pipewire-pulse`, `xdg-desktop-portal-wlr`
+
+2. **Optional: Add to autostart**
+
+   In some situations the portal may not start automatically. You can add this to your autostart script to ensure it launches:
+
+   ```bash
+   /usr/lib/xdg-desktop-portal-wlr &
+   ```
+
+3. **Restart your computer** to apply changes.
+
+### Known Issues
+
+- **Window screen sharing:** Some applications may have issues sharing individual windows. See [#184](https://github.com/mangowm/mango/pull/184) for workarounds.
+
+- **Screen recording lag:** If you experience stuttering during screen recording, see [xdg-desktop-portal-wlr#351](https://github.com/emersion/xdg-desktop-portal-wlr/issues/351).
+
+## Clipboard Manager
+
+Use `cliphist` to manage clipboard history.
+
+**Dependencies:** `wl-clipboard`, `cliphist`, `wl-clip-persist`
+
+**Autostart Config:**
+
+```bash
+# Keep clipboard content after app closes
+wl-clip-persist --clipboard regular --reconnect-tries 0 &
+
+# Watch clipboard and store history
+wl-paste --type text --watch cliphist store &
+```
+
+## GNOME Keyring
+
+If you need to store passwords or secrets (e.g., for VS Code or Minecraft launchers), install `gnome-keyring`.
+
+**Configuration:**
+
+Add the following to `~/.config/xdg-desktop-portal/mango-portals.conf`:
+
+```ini
+[preferred]
+default=gtk
+org.freedesktop.impl.portal.ScreenCast=wlr
+org.freedesktop.impl.portal.Screenshot=wlr
+org.freedesktop.impl.portal.Secret=gnome-keyring
+org.freedesktop.impl.portal.Inhibit=none
+```
+
+## File Picker (File Selector)
+
+**Dependencies:** `xdg-desktop-portal`, `xdg-desktop-portal-gtk`
+
+Reboot your computer once to apply.

docs/faq.md

@@ -0,0 +1,101 @@
+---
+title: FAQ
+description: Frequently asked questions and troubleshooting.
+---
+
+### How do I arrange tiled windows with my mouse?
+
+You can enable the `drag_tile_to_tile` option in your config. This allows you to drag a tiled window onto another to swap them.
+
+```ini
+drag_tile_to_tile=1
+```
+
+---
+
+### Why is my background blurry or why does blur look wrong?
+
+Blur applies to the transparent areas of windows. To disable it entirely, set `blur=0`.
+
+If you are experiencing **performance issues with blur**, make sure `blur_optimized=1` (the default). This caches the wallpaper as the blur background, which is much cheaper on the GPU:
+
+```ini
+blur_optimized=1
+```
+
+---
+
+### Blur shows my wallpaper instead of the real background content
+
+This is expected behavior when `blur_optimized=1` (the default). The optimizer caches the wallpaper to reduce GPU load — windows will blur against the wallpaper rather than the actual content stacked beneath them.
+
+If you want blur to composite against the true background (i.e., show whatever is actually behind the window), set:
+
+```ini
+blur_optimized=0
+```
+
+> **Warning:** Disabling `blur_optimized` significantly increases GPU consumption and may cause rendering lag, especially on lower-end hardware.
+
+---
+
+### My games are lagging or stuttering
+
+Try enabling **SyncObj** timeline support and **Adaptive Sync** (VRR) if your monitor supports it.
+
+```ini
+syncobj_enable=1
+adaptive_sync=1
+```
+
+---
+
+### My games have high input latency
+
+You can enable **Tearing** (similar to VSync off).
+
+First, enable it globally:
+
+```ini
+allow_tearing=1
+```
+
+Then force it for your specific game:
+
+```ini
+windowrule=force_tearing:1,title:Counter-Strike 2
+```
+
+> **Warning:** Some graphics cards require setting `WLR_DRM_NO_ATOMIC=1` before mango starts for tearing to work. Add it to `/etc/environment` and reboot, or launch mango with `WLR_DRM_NO_ATOMIC=1 mango`. See [Monitors — Tearing](/docs/configuration/monitors#tearing-game-mode) for details.
+
+---
+
+### How do I use pipes `|` in spawn commands?
+
+The standard `spawn` command does not support shell pipes directly. You must use `spawn_shell` instead.
+
+```ini
+bind=SUPER,P,spawn_shell,echo "hello" | rofi -dmenu
+```
+
+---
+
+### Certain key combinations do not work on my keyboard layout.
+
+`bind` automatically converts keysym to keycode, which is compatible with most layouts but can sometimes be imprecise. If a key combination is not triggering, use the **keycode** directly instead of the key name.
+
+Run `wev` and press the key to find its keycode, then use it in your bind:
+
+```ini
+# Instead of:
+bind=ALT,q,killclient
+
+# Use the keycode (e.g., code:24 = q on most layouts):
+bind=ALT,code:24,killclient
+```
+
+You can also use `binds` (the `s` flag) to match by keysym instead of keycode:
+
+```ini
+binds=ALT,q,killclient
+```

docs/index.md

@@ -0,0 +1,42 @@
+---
+title: Introduction
+description: A lightweight and feature-rich Wayland compositor based on dwl.
+---
+
+
+**mango** is a Wayland compositor based on [dwl](https://codeberg.org/dwl/dwl/). It aims to be as lightweight as `dwl` and can be built completely within a few seconds, without compromising on functionality.
+
+> **Philosophy:** **Lightweight & Fast**: mango is designed to be minimal yet functional. It compiles in seconds and offers a robust set of features out of the box.
+
+## Feature Highlights
+
+Beyond basic window management, mangowm provides a rich set of features designed for a modern Wayland experience.
+
+- **[Animations](/docs/visuals/animations)** — Smooth, customizable animations for opening, moving, closing windows and tag switching.
+- **[Layouts](/docs/window-management/layouts)** — Supports Scroller, Master-Stack, Monocle, Grid, Deck, and more, with per-tag layouts.
+- **[Visual Effects](/docs/visuals/effects)** — Built-in blur, shadows, corner radius, and opacity effects powered by scenefx.
+- **[IPC & Scripting](/docs/ipc)** — Control the compositor externally with robust IPC support for custom scripts and widgets.
+
+## Additional Features
+
+- **XWayland Support** — Excellent compatibility for legacy X11 applications.
+- **Tag System** — Uses tags instead of workspaces, allowing separate window layouts for each tag.
+- **Input Methods** — Great support for text input v2/v3 (Fcitx5, IBus).
+- **Window States** — Rich states including swallow, minimize, maximize, fullscreen, and overlay.
+- **Hot-Reload Config** — Simple external configuration that supports hot-reloading without restarting.
+- **Scratchpads** — Support for both Sway-like and named scratchpads.
+
+## Community
+
+- **[Join the mangowm Discord](https://discord.gg/CPjbDxesh5)** — Chat with the community, get support, share your setup, and stay updated with the latest mangowm news.
+- **[Join the GitHub Discussions](https://github.com/mangowm/mango/discussions)** — Ask questions, request features, report issues, or share ideas directly with contributors and other users.
+
+## Acknowledgements
+
+This project is built upon the hard work of several open-source projects:
+
+- **[wlroots](https://gitlab.freedesktop.org/wlroots/wlroots)** — Implementation of the Wayland protocol.
+- **[owl](https://github.com/dqrk0jeste/owl)** — Basal window animation reference.
+- **[dwl](https://codeberg.org/dwl/dwl)** — Basal dwl features.
+- **[sway](https://github.com/swaywm/sway)** — Sample implementation of the Wayland protocol.
+- **[scenefx](https://github.com/wlrfx/scenefx)** — Library to simplify adding window effects.

docs/installation.md

@@ -0,0 +1,231 @@
+---
+title: Installation
+description: Install mangowm on Arch, Fedora, Gentoo, Guix System, NixOS, PikaOS, or build from source.
+---
+
+## Package Installation
+
+mangowm is available as a pre-built package on several distributions. Choose your distribution below.
+
+---
+
+### Arch Linux
+
+mangowm is available in the **Arch User Repository (AUR)**.
+
+You can install it using an AUR helper like `yay` or `paru`:
+
+```bash
+yay -S mangowm-git
+```
+
+> **Tip:** This package pulls the latest git version, ensuring you have the newest features and fixes.
+
+---
+
+### Fedora
+
+The package is in the third-party **Terra repository**. First, add the Terra Repository.
+
+> **Warning:** Both commands require root privileges. Use `sudo` if needed.
+
+```bash
+dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
+```
+
+Then, install the package:
+
+```bash
+dnf install mangowm
+```
+
+---
+
+### Gentoo
+
+The package is hosted in the community-maintained **GURU** repository.
+
+1. **Add the GURU repository**
+   ```bash
+   emerge --ask --verbose eselect-repository
+   eselect repository enable guru
+   emerge --sync guru
+   ```
+
+2. **Unmask packages**
+   Add the required packages to your `package.accept_keywords` file:
+   - `gui-libs/scenefx`
+   - `gui-wm/mangowm`
+
+3. **Install mango**
+   ```bash
+   emerge --ask --verbose gui-wm/mangowm
+   ```
+
+---
+
+### Guix System
+
+The package definition is described in the source repository.
+
+1. **Add mango channel**
+   Add to `$HOME/.config/guix/channels.scm`:
+   ```scheme
+   (cons (channel
+           (name 'mangowm)
+           (url "https://github.com/mangowm/mango.git")
+           (branch "main"))
+         %default-channels)
+   ```
+
+2. **Install**
+   After running `guix pull`, you can install mangowm:
+   ```bash
+   guix install mangowm
+   ```
+
+   Or add it to your system configuration using the mangowm module:
+   ```scheme
+   (use-modules (mangowm))
+
+   (packages (cons*
+               mangowm-git
+               ... ;; Other packages
+               %base-packages))
+   ```
+
+> **Tip:** For more information, see the [Guix System documentation](https://guix.gnu.org/manual/devel/en/html_node/Channels.html).
+
+---
+
+### NixOS
+
+The repository provides a Flake with a NixOS module.
+
+1. **Add flake input**
+   ```nix
+   # flake.nix
+   {
+     inputs = {
+       nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+       mangowm = {
+         url = "github:mangowm/mango";
+         inputs.nixpkgs.follows = "nixpkgs";
+       };
+       # other inputs ...
+     };
+   }
+   ```
+
+2. **Import the NixOS module**
+
+   **Option A — Import in `configuration.nix`:**
+   ```nix
+   # configuration.nix (or any other file that you import)
+   {inputs, ...}: {
+     imports = [
+       inputs.mangowm.nixosModules.mango
+       # .. other imports ...
+     ];
+
+     # ...
+   }
+   ```
+
+   **Option B — Import directly in flake:**
+   ```nix
+   # flake.nix
+   {
+     # ...
+
+     outputs = { self, nixpkgs, mangowm, ...}@inputs: let
+       inherit (nixpkgs) lib;
+       # ...
+     in {
+       nixosConfigurations.YourHostName = lib.nixosSystem {
+         modules = [
+           mangowm.nixosModules.mango # or inputs.mangowm.nixosModules.mango
+           # other imports ...
+         ];
+       };
+     }
+   }
+   ```
+
+3. **Enable the module**
+   ```nix
+   # configuration.nix (or any other file that you import)
+   {
+     programs.mango.enable = true;
+   }
+   ```
+
+4. **Extra options**
+   - `programs.mango.package` — the mango package to use, allows usage of custom mango drvs
+   - `programs.mango.addLoginEntry` (default: `true`) — adds login entry to the display manager
+
+---
+
+### PikaOS
+
+mangowm is available in the **PikaOS package repository**.
+
+You can install it using the `pikman` package manager:
+
+```bash
+pikman install mangowc
+```
+
+---
+
+## Building from Source
+
+If your distribution isn't listed above, or you want the latest unreleased changes, you can build mangowm from source.
+
+> **Info:** Ensure the following dependencies are installed before proceeding:
+> - `glibc`
+> - `wayland`
+> - `wayland-protocols`
+> - `libinput`
+> - `libdrm`
+> - `libxkbcommon`
+> - `pixman`
+> - `git`
+> - `meson`
+> - `ninja`
+> - `libdisplay-info`
+> - `libliftoff`
+> - `hwdata`
+> - `seatd`
+> - `pcre2`
+> - `xorg-xwayland`
+> - `libxcb`
+
+You will need to build `wlroots` and `scenefx` manually as well.
+
+1. **Build wlroots**
+   Clone and install the specific version required (check README for latest version).
+   ```bash
+   git clone -b 0.19.2 https://gitlab.freedesktop.org/wlroots/wlroots.git
+   cd wlroots
+   meson build -Dprefix=/usr
+   sudo ninja -C build install
+   ```
+
+2. **Build scenefx**
+   This library handles the visual effects.
+   ```bash
+   git clone -b 0.4.1 https://github.com/wlrfx/scenefx.git
+   cd scenefx
+   meson build -Dprefix=/usr
+   sudo ninja -C build install
+   ```
+
+3. **Build mangowm**
+   Finally, compile the compositor itself.
+   ```bash
+   git clone https://github.com/mangowm/mango.git
+   cd mango
+   meson build -Dprefix=/usr
+   sudo ninja -C build install
+   ```

docs/ipc.md

@@ -0,0 +1,154 @@
+---
+title: IPC
+description: Control mangowm programmatically using mmsg.
+---
+
+## Introduction
+
+mangowm includes a powerful IPC (Inter-Process Communication) tool called `mmsg`. This allows you to query the window manager's state, watch for events, and execute commands from external scripts.
+
+## Basic Usage
+
+The general syntax for `mmsg` is:
+
+```bash
+mmsg [-OTLq]
+mmsg [-o <output>] -s [-t <tags>] [-l <layout>] [-c <tags>] [-d <cmd>,<arg1>,<arg2>,<arg3>,<arg4>,<arg5>]
+mmsg [-o <output>] (-g | -w) [-OotlcvmfxekbA]
+```
+
+### Options
+
+| Flag | Description |
+| :--- | :--- |
+| `-q` | Quit mangowm. |
+| `-g` | **Get** values (tags, layout, focused client). |
+| `-s` | **Set** values (switch tags, layouts). |
+| `-w` | **Watch** mode (streams events). |
+| `-O` | Get all output (monitor) information. |
+| `-T` | Get number of tags. |
+| `-L` | Get all available layouts. |
+| `-o` | Select output (monitor). |
+| `-t` | Get/set selected tags (set with `[+-^.]`). |
+| `-l` | Get/set current layout. |
+| `-c` | Get title and appid of focused client. |
+| `-v` | Get visibility of statusbar. |
+| `-m` | Get fullscreen status. |
+| `-f` | Get floating status. |
+| `-d` | **Dispatch** an internal command. |
+| `-x` | Get focused client geometry. |
+| `-e` | Get the name of the last focused layer. |
+| `-k` | Get current keyboard layout. |
+| `-b` | Get current keybind mode. |
+| `-A` | Get scale factor of monitor. |
+
+## Examples
+
+### Tag Management
+
+You can perform arithmetic on tags using the `-t` flag with `-s` (set).
+
+```bash
+# Switch to Tag 1
+mmsg -t 1
+
+# Add Tag 2 to current view (Multiview)
+mmsg -s -t 2+
+
+# Remove Tag 2 from current view
+mmsg -s -t 2-
+
+# Toggle Tag 2
+mmsg -s -t 2^
+```
+
+### Layouts
+
+Switch layouts programmatically. Layout codes: `S` (Scroller), `T` (Tile), `G` (Grid), `M` (Monocle), `K` (Deck), `CT` (Center Tile), `RT` (Right Tile), `VS` (Vertical Scroller), `VT` (Vertical Tile), `VG` (Vertical Grid), `VK` (Vertical Deck), `TG` (TGMix).
+
+```bash
+# Switch to Scroller
+mmsg -l "S"
+
+# Switch to Tile
+mmsg -l "T"
+```
+
+### Dispatching Commands
+
+Any command available in `config.conf` keybindings can be run via IPC.
+
+```bash
+# Close the focused window
+mmsg -d killclient
+
+# Resize window by +10 width
+mmsg -d resizewin,+10,0
+
+# Toggle fullscreen
+mmsg -d togglefullscreen
+
+# Disable a monitor power
+mmsg -d disable_monitor,eDP-1
+```
+
+### Monitoring & Status
+
+Use `-g` or `-w` to build custom status bars or automation scripts.
+
+```bash
+# Watch for all message changes
+mmsg -w
+
+# Get all messages without watch
+mmsg -g
+
+# Watch focused client appid and title
+mmsg -w -c
+
+# Get all available outputs
+mmsg -O
+
+# Get all tags message
+mmsg -g -t
+
+# Get current focused client message
+mmsg -g -c
+
+# Get current keyboard layout
+mmsg -g -k
+
+# Get current keybind mode
+mmsg -g -b
+
+# Get scale factor of current monitor
+mmsg -g -A
+```
+
+#### Tag Message Format
+
+- State: 0 → none, 1 → active, 2 → urgent
+
+Example output:
+
+| Monitor | Tag Number | Tag State | Clients in Tag | Focused Client |
+|---------|------------|-----------|----------------|----------------|
+| eDP-1   | tag 2      | 0         | 1              | 0              |
+
+| Monitor | occupied tags mask | active tags mask | urgent tags mask |
+|---------|--------------------|------------------|------------------|
+| eDP-1   | 14                 | 6                | 0                |
+
+## Virtual Monitors
+
+You can create headless outputs for screen mirroring or remote desktop access (e.g., Sunshine/Moonlight).
+
+```bash
+# Create a virtual output
+mmsg -d create_virtual_output
+
+# Configure it (set resolution)
+wlr-randr --output HEADLESS-1 --pos 1920,0 --mode 1920x1080@60Hz
+
+# Destroy all virtual outputs
+mmsg -d destroy_all_virtual_output

docs/meta.json

@@ -0,0 +1,14 @@
+{
+	"title": "mangowm",
+	"pages": [
+		"index",
+		"installation",
+		"quick-start",
+		"configuration",
+		"visuals",
+		"window-management",
+		"bindings",
+		"ipc",
+		"faq"
+	]
+}

docs/quick-start.md

@@ -0,0 +1,88 @@
+---
+title: Quick Start
+description: Basic configuration and first steps with mangowm.
+---
+
+Now that you have mangowm installed, let's get your environment set up.
+
+## Initial Setup
+
+1. **Create Configuration Directory**
+
+   mangowm looks for configuration files in `~/.config/mango/`.
+
+   ```bash
+   mkdir -p ~/.config/mango
+   ```
+
+2. **Copy Default Config**
+
+   A default configuration file is provided at `/etc/mango/config.conf`. Copy it to your local directory to start customizing.
+
+   ```bash
+   cp /etc/mango/config.conf ~/.config/mango/config.conf
+   ```
+
+3. **Launch mangowm**
+
+   You can now start the compositor from your TTY.
+
+   ```bash
+   mango
+   ```
+
+   Optional: To specify a custom config file path:
+
+   ```bash
+   mango -c /path/to/your/config.conf
+   ```
+
+## Essential Keybindings
+
+mangowm uses the following keybinds by default:
+
+| Key Combination | Action |
+| :--- | :--- |
+| `Alt` + `Return` | Open Terminal (defaults to `foot`) |
+| `Alt` + `Space` | Open Launcher (defaults to `rofi`) |
+| `Alt` + `Q` | Close (Kill) the active window |
+| `Super` + `M` | Quit mangowm |
+| `Super` + `F` | Toggle Fullscreen |
+| `Alt` + `Arrow Keys` | Move focus (Left, Right, Up, Down) |
+| `Ctrl` + `1-9` | Switch to Tag 1-9 |
+| `Alt` + `1-9` | Move window to Tag 1-9 |
+
+> **Warning:** Some default bindings rely on specific tools like `foot` (terminal) and `rofi` (launcher). Ensure you have them installed or update your `config.conf` to use your preferred alternatives.
+
+## Recommended Tools
+
+To get a fully functional desktop experience, we recommend installing the following components:
+
+| Category | Recommended Tools |
+| :--- | :--- |
+| Application Launcher | rofi, bemenu, wmenu, fuzzel |
+| Terminal Emulator | foot, wezterm, alacritty, kitty, ghostty |
+| Status Bar | waybar, eww, quickshell, ags |
+| Desktop Shell | Noctalia, DankMaterialShell |
+| Wallpaper Setup | swww, swaybg |
+| Notification Daemon | swaync, dunst, mako |
+| Desktop Portal | xdg-desktop-portal, xdg-desktop-portal-wlr, xdg-desktop-portal-gtk |
+| Clipboard | wl-clipboard, wl-clip-persist, cliphist |
+| Gamma Control / Night Light | wlsunset, gammastep |
+| Miscellaneous | xfce-polkit, wlogout |
+
+## Example Configuration
+
+Check out the [example configuration](https://github.com/DreamMaoMao/mango-config) by the creator of mangowm, including complete setups for mangowm, Waybar, Rofi, and more.
+
+```bash
+git clone https://github.com/DreamMaoMao/mango-config.git ~/.config/mango
+```
+
+## Next Steps
+
+Now that you are up and running, dive deeper into customizing mangowm:
+
+- [Configure Monitors](/docs/configuration/monitors) — Set up resolution, scaling, and multi-monitor layouts.
+- [Window Rules](/docs/window-management/rules#window-rules) — Define how specific applications should behave.
+- [Appearance](/docs/visuals/theming) — Customize colors, borders, gaps, and effects.

docs/visuals/animations.md

@@ -0,0 +1,108 @@
+---
+title: Animations
+description: Configure smooth transitions for windows and layers.
+---
+
+## Enabling Animations
+
+mangowm supports animations for both standard windows and layer shell surfaces (like bars and notifications).
+
+```ini
+animations=1
+layer_animations=1
+```
+
+## Animation Types
+
+You can define different animation styles for opening and closing windows and layer surfaces.
+
+Available types: `slide`, `zoom`, `fade`, `none`.
+
+```ini
+animation_type_open=zoom
+animation_type_close=slide
+layer_animation_type_open=slide
+layer_animation_type_close=slide
+```
+
+## Fade Settings
+
+Control the fade-in and fade-out effects for animations.
+
+```ini
+animation_fade_in=1
+animation_fade_out=1
+fadein_begin_opacity=0.5
+fadeout_begin_opacity=0.5
+```
+
+- `animation_fade_in` — Enable fade-in effect (0: disable, 1: enable)
+- `animation_fade_out` — Enable fade-out effect (0: disable, 1: enable)
+- `fadein_begin_opacity` — Starting opacity for fade-in animations (0.0–1.0)
+- `fadeout_begin_opacity` — Starting opacity for fade-out animations (0.0–1.0)
+
+## Zoom Settings
+
+Adjust the zoom ratios for zoom animations.
+
+```ini
+zoom_initial_ratio=0.3
+zoom_end_ratio=0.8
+```
+
+- `zoom_initial_ratio` — Initial zoom ratio
+- `zoom_end_ratio` — End zoom ratio
+
+## Durations
+
+Control the speed of animations (in milliseconds).
+
+| Setting | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `animation_duration_move` | integer | `500` | Move animation duration (ms) |
+| `animation_duration_open` | integer | `400` | Open animation duration (ms) |
+| `animation_duration_tag` | integer | `300` | Tag animation duration (ms) |
+| `animation_duration_close` | integer | `300` | Close animation duration (ms) |
+| `animation_duration_focus` | integer | `0` | Focus change (opacity transition) animation duration (ms) |
+
+```ini
+animation_duration_move=500
+animation_duration_open=400
+animation_duration_tag=300
+animation_duration_close=300
+animation_duration_focus=0
+```
+
+## Custom Bezier Curves
+
+Bezier curves determine the "feel" of an animation (e.g., linear vs. bouncy). The format is `x1,y1,x2,y2`.
+
+You can visualize and generate curve values using online tools like [cssportal.com](https://www.cssportal.com/css-cubic-bezier-generator/) or [easings.net](https://easings.net).
+
+| Setting | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `animation_curve_open` | string | `0.46,1.0,0.29,0.99` | Open animation bezier curve |
+| `animation_curve_move` | string | `0.46,1.0,0.29,0.99` | Move animation bezier curve |
+| `animation_curve_tag` | string | `0.46,1.0,0.29,0.99` | Tag animation bezier curve |
+| `animation_curve_close` | string | `0.46,1.0,0.29,0.99` | Close animation bezier curve |
+| `animation_curve_focus` | string | `0.46,1.0,0.29,0.99` | Focus change (opacity transition) animation bezier curve |
+| `animation_curve_opafadein` | string | `0.46,1.0,0.29,0.99` | Open opacity animation bezier curve |
+| `animation_curve_opafadeout` | string | `0.5,0.5,0.5,0.5` | Close opacity animation bezier curve |
+
+```ini
+animation_curve_open=0.46,1.0,0.29,0.99
+animation_curve_move=0.46,1.0,0.29,0.99
+animation_curve_tag=0.46,1.0,0.29,0.99
+animation_curve_close=0.46,1.0,0.29,0.99
+animation_curve_focus=0.46,1.0,0.29,0.99
+animation_curve_opafadein=0.46,1.0,0.29,0.99
+animation_curve_opafadeout=0.5,0.5,0.5,0.5
+```
+
+## Tag Animation Direction
+
+Control the direction of tag switch animations.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `tag_animation_direction` | `1` | Tag animation direction (1: horizontal, 0: vertical) |

docs/visuals/effects.md

@@ -0,0 +1,82 @@
+---
+title: Window Effects
+description: Add visual polish with blur, shadows, and opacity.
+---
+
+## Blur
+
+Blur creates a frosted glass effect for transparent windows.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `blur` | `0` | Enable blur for windows. |
+| `blur_layer` | `0` | Enable blur for layer surfaces (like bars/docks). |
+| `blur_optimized` | `1` | Caches the wallpaper and blur background, significantly reducing GPU usage. Disabling it will significantly increase GPU consumption and may cause rendering lag. **Highly recommended.** |
+| `blur_params_radius` | `5` | The strength (radius) of the blur. |
+| `blur_params_num_passes` | `1` | Number of passes. Higher = smoother but more expensive. |
+| `blur_params_noise` | `0.02` | Blur noise level. |
+| `blur_params_brightness` | `0.9` | Blur brightness adjustment. |
+| `blur_params_contrast` | `0.9` | Blur contrast adjustment. |
+| `blur_params_saturation` | `1.2` | Blur saturation adjustment. |
+
+> **Warning:** Blur has a relatively high impact on performance. If your hardware is limited, it is not recommended to enable it. If you experience lag with blur on, ensure `blur_optimized=1` — disabling it will significantly increase GPU consumption and may cause rendering lag. To disable blur entirely, set `blur=0`.
+
+---
+
+## Shadows
+
+Drop shadows help distinguish floating windows from the background.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `shadows` | `0` | Enable shadows. |
+| `layer_shadows` | `0` | Enable shadows for layer surfaces. |
+| `shadow_only_floating` | `1` | Only draw shadows for floating windows (saves performance). |
+| `shadows_size` | `10` | Size of the shadow. |
+| `shadows_blur` | `15` | Shadow blur amount. |
+| `shadows_position_x` | `0` | Shadow X offset. |
+| `shadows_position_y` | `0` | Shadow Y offset. |
+| `shadowscolor` | `0x000000ff` | Color of the shadow. |
+
+```ini
+# Example shadows configuration
+shadows=1
+layer_shadows=1
+shadow_only_floating=1
+shadows_size=12
+shadows_blur=15
+shadows_position_x=0
+shadows_position_y=0
+shadowscolor=0x000000ff
+```
+
+---
+
+## Opacity & Corner Radius
+
+Control the transparency and roundness of your windows.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `border_radius` | `0` | Window corner radius in pixels. |
+| `border_radius_location_default` | `0` | Corner radius location: `0` (all), `1` (top-left), `2` (top-right), `3` (bottom-left), `4` (bottom-right), `5` (closest corner). |
+| `no_radius_when_single` | `0` | Disable radius if only one window is visible. |
+| `focused_opacity` | `1.0` | Opacity for the active window (0.0 - 1.0). |
+| `unfocused_opacity` | `1.0` | Opacity for inactive windows (0.0 - 1.0). |
+
+```ini
+# Window corner radius in pixels
+border_radius=0
+
+# Corner radius location (0=all, 1=top-left, 2=top-right, 3=bottom-left, 4=bottom-right)
+border_radius_location_default=0
+
+# Disable radius if only one window is visible
+no_radius_when_single=0
+
+# Opacity for the active window (0.0 - 1.0)
+focused_opacity=1.0
+
+# Opacity for inactive windows
+unfocused_opacity=1.0
+```

docs/visuals/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Visuals",
+	"pages": ["theming", "status-bar", "effects", "animations"]
+}

docs/visuals/status-bar.md

@@ -0,0 +1,141 @@
+---
+title: Status Bar
+description: Configure Waybar for mangowm.
+---
+
+## Module Configuration
+
+mangowm is compatible with Waybar's `ext/workspaces` module (Wayland standard) or the `dwl/tags` module. We recommend `ext/workspaces` for the best experience.
+
+> **Tip:** You can also use the `dwl/tags` module, but `ext/workspaces` provides better integration with mangowm's features. The `ext/workspaces` module requires **Waybar > 0.14.0**.
+
+### `config.jsonc`
+
+Add the following to your Waybar configuration:
+
+```jsonc
+{
+  "modules-left": [
+    "ext/workspaces",
+    "dwl/window"
+  ],
+  "ext/workspaces": {
+    "format": "{icon}",
+    "ignore-hidden": true,
+    "on-click": "activate",
+    "on-click-right": "deactivate",
+    "sort-by-id": true
+  },
+  "dwl/window": {
+    "format": "[{layout}] {title}"
+  }
+}
+```
+
+## Styling
+
+You can style the tags using standard CSS in `style.css`.
+
+### `style.css`
+
+```css
+#workspaces {
+  border-radius: 4px;
+  border-width: 2px;
+  border-style: solid;
+  border-color: #c9b890;
+  margin-left: 4px;
+  padding-left: 10px;
+  padding-right: 6px;
+  background: rgba(40, 40, 40, 0.76);
+}
+
+#workspaces button {
+  border: none;
+  background: none;
+  box-shadow: inherit;
+  text-shadow: inherit;
+  color: #ddca9e;
+  padding: 1px;
+  padding-left: 1px;
+  padding-right: 1px;
+  margin-right: 2px;
+  margin-left: 2px;
+}
+
+#workspaces button.hidden {
+  color: #9e906f;
+  background-color: transparent;
+}
+
+#workspaces button.visible {
+  color: #ddca9e;
+}
+
+#workspaces button:hover {
+  color: #d79921;
+}
+
+#workspaces button.active {
+  background-color: #ddca9e;
+  color: #282828;
+  margin-top: 5px;
+  margin-bottom: 5px;
+  padding-top: 1px;
+  padding-bottom: 0px;
+  border-radius: 3px;
+}
+
+#workspaces button.urgent {
+  background-color: #ef5e5e;
+  color: #282828;
+  margin-top: 5px;
+  margin-bottom: 5px;
+  padding-top: 1px;
+  padding-bottom: 0px;
+  border-radius: 3px;
+}
+
+#tags {
+  background-color: transparent;
+}
+
+#tags button {
+  background-color: #fff;
+  color: #a585cd;
+}
+
+#tags button:not(.occupied):not(.focused) {
+  font-size: 0;
+  min-width: 0;
+  min-height: 0;
+  margin: -17px;
+  padding: 0;
+  color: transparent;
+  background-color: transparent;
+}
+
+#tags button.occupied {
+  background-color: #fff;
+  color: #cdc885;
+}
+
+#tags button.focused {
+  background-color: rgb(186, 142, 213);
+  color: #fff;
+}
+
+#tags button.urgent {
+  background: rgb(171, 101, 101);
+  color: #fff;
+}
+
+#window {
+  background-color: rgb(237, 196, 147);
+  color: rgb(63, 37, 5);
+}
+```
+
+## Complete Configuration Example
+
+> **Tip:** You can find a complete Waybar configuration for mangowm at [waybar-config](https://github.com/DreamMaoMao/waybar-config).

docs/visuals/theming.md

@@ -0,0 +1,59 @@
+---
+title: Theming
+description: Customize the visual appearance of borders, colors, and the cursor.
+---
+
+## Dimensions
+
+Control the sizing of window borders and gaps.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `borderpx` | `4` | Border width in pixels. |
+| `gappih` | `5` | Horizontal inner gap (between windows). |
+| `gappiv` | `5` | Vertical inner gap. |
+| `gappoh` | `10` | Horizontal outer gap (between windows and screen edges). |
+| `gappov` | `10` | Vertical outer gap. |
+
+## Colors
+
+Colors are defined in `0xRRGGBBAA` hex format.
+
+```ini
+# Background color of the root window
+rootcolor=0x323232ff
+
+# Inactive window border
+bordercolor=0x444444ff
+
+# Active window border
+focuscolor=0xc66b25ff
+
+# Urgent window border (alerts)
+urgentcolor=0xad401fff
+```
+
+### State-Specific Colors
+
+You can also color-code windows based on their state:
+
+| State | Config Key | Default Color |
+| :--- | :--- | :--- |
+| Maximized | `maximizescreencolor` | `0x89aa61ff` |
+| Scratchpad | `scratchpadcolor` | `0x516c93ff` |
+| Global | `globalcolor` | `0xb153a7ff` |
+| Overlay | `overlaycolor` | `0x14a57cff` |
+
+> **Tip:** For scratchpad window sizing, see [Scratchpad](/docs/window-management/scratchpad) configuration.
+
+## Cursor Theme
+
+Set the size and theme of your mouse cursor.
+
+```ini
+cursor_size=24
+cursor_theme=Adwaita
+```
+
+> **Tip:** You may also want to set the `XCURSOR_SIZE` environment variable to match:
+> `env=XCURSOR_SIZE,24`

docs/window-management/layouts.md

@@ -0,0 +1,99 @@
+---
+title: Layouts
+description: Configure and switch between different window layouts.
+---
+
+## Supported Layouts
+
+mangowm supports a variety of layouts that can be assigned per tag.
+
+- `tile`
+- `scroller`
+- `monocle`
+- `grid`
+- `deck`
+- `center_tile`
+- `vertical_tile`
+- `right_tile`
+- `vertical_scroller`
+- `vertical_grid`
+- `vertical_deck`
+- `tgmix`
+
+---
+
+## Scroller Layout
+
+The Scroller layout positions windows in a scrollable strip, similar to PaperWM.
+
+### Configuration
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `scroller_structs` | `20` | Width reserved on sides when window ratio is 1. |
+| `scroller_default_proportion` | `0.9` | Default width proportion for new windows. |
+| `scroller_focus_center` | `0` | Always center the focused window (1 = enable). |
+| `scroller_prefer_center` | `0` | Center focused window only if it was outside the view. |
+| `scroller_prefer_overspread` | `1` | Allow windows to overspread when there's extra space. |
+| `edge_scroller_pointer_focus` | `1` | Focus windows even if partially off-screen. |
+| `scroller_proportion_preset` | `0.5,0.8,1.0` | Presets for cycling window widths. |
+| `scroller_ignore_proportion_single` | `1` | Ignore proportion adjustments for single windows. |
+| `scroller_default_proportion_single` | `1.0` | Default proportion for single windows in scroller. **Requires `scroller_ignore_proportion_single=0` to take effect.** |
+
+> **Warning:** `scroller_prefer_overspread`, `scroller_focus_center`, and `scroller_prefer_center` interact with each other. Their priority order is:
+>
+> **scroller_prefer_overspread > scroller_focus_center > scroller_prefer_center**
+>
+> To ensure a lower-priority setting takes effect, you must set all higher-priority options to `0`.
+
+```ini
+# Example scroller configuration
+scroller_structs=20
+scroller_default_proportion=0.9
+scroller_focus_center=0
+scroller_prefer_center=0
+scroller_prefer_overspread=1
+edge_scroller_pointer_focus=1
+scroller_default_proportion_single=1.0
+scroller_proportion_preset=0.5,0.8,1.0
+```
+
+---
+
+## Master-Stack Layouts
+
+These settings apply to layouts like `tile` and `center_tile`.
+
+| Setting | Default | Description |
+| :--- | :--- | :--- |
+| `new_is_master` | `1` | New windows become the master window. |
+| `default_mfact` | `0.55` | The split ratio between master and stack areas. |
+| `default_nmaster` | `1` | Number of allowed master windows. |
+| `smartgaps` | `0` | Disable gaps when only one window is present. |
+| `center_master_overspread` | `0` | (Center Tile) Master spreads across screen if no stack exists. |
+| `center_when_single_stack` | `1` | (Center Tile) Center master when only one stack window exists. |
+
+```ini
+# Example master-stack configuration
+new_is_master=1
+smartgaps=0
+default_mfact=0.55
+default_nmaster=1
+```
+
+---
+
+## Switching Layouts
+
+You can switch layouts dynamically or set a default for specific tags using [Tag Rules](/docs/window-management/rules#tag-rules).
+
+**Keybinding Examples:**
+
+```ini
+# Cycle through layouts
+bind=SUPER,n,switch_layout
+
+# Set specific layout
+bind=SUPER,t,setlayout,tile
+bind=SUPER,s,setlayout,scroller
+```

docs/window-management/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Window Management",
+	"pages": ["layouts", "rules", "overview", "scratchpad"]
+}

docs/window-management/overview.md

@@ -0,0 +1,36 @@
+---
+title: Overview
+description: Configure the overview mode for window navigation.
+---
+
+## Overview Settings
+
+| Setting | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `hotarea_size` | integer | `10` | Hot area size in pixels. |
+| `enable_hotarea` | integer | `1` | Enable hot areas (0: disable, 1: enable). |
+| `hotarea_corner` | integer | `2` | Hot area corner (0: top-left, 1: top-right, 2: bottom-left, 3: bottom-right). |
+| `ov_tab_mode` | integer | `0` | Overview tab mode (0: disable, 1: enable). |
+| `overviewgappi` | integer | `5` | Inner gap in overview mode. |
+| `overviewgappo` | integer | `30` | Outer gap in overview mode. |
+
+### Setting Descriptions
+
+- `enable_hotarea` — Toggles overview when the cursor enters the configured corner.
+- `hotarea_size` — Size of the hot area trigger zone in pixels.
+- `hotarea_corner` — Corner that triggers the hot area (0: top-left, 1: top-right, 2: bottom-left, 3: bottom-right).
+- `ov_tab_mode` — Circles focus through windows in overview; releasing the mod key exits overview.
+
+### Mouse Interaction in Overview
+
+When in overview mode:
+
+- **Left mouse button** — Jump to (focus) a window.
+- **Right mouse button** — Close a window.
+
+To enable this behavior, add the following mouse bindings to your config:
+
+```ini
+mousebind=NONE,btn_left,toggleoverview,1
+mousebind=NONE,btn_right,killclient,0
+```

docs/window-management/rules.md

@@ -0,0 +1,249 @@
+---
+title: Rules
+description: Define behavior for specific windows, tags, and layers.
+---
+
+## Window Rules
+
+Window rules allow you to set specific properties (floating, opacity, size, animations, etc.) for applications based on their `appid` or `title`. You can set all parameters in one line, and if you both set appid and title, the window will only follow the rules when appid and title both match.
+
+**Format:**
+
+```ini
+windowrule=Parameter:Values,title:Values
+windowrule=Parameter:Values,Parameter:Values,appid:Values,title:Values
+```
+
+### State & Behavior Parameters
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `appid` | string | Any | Match by application ID, supports regex |
+| `title` | string | Any | Match by window title, supports regex |
+| `isfloating` | integer | `0` / `1` | Force floating state |
+| `isfullscreen` | integer | `0` / `1` | Force fullscreen state |
+| `isfakefullscreen` | integer | `0` / `1` | Force fake-fullscreen state (window stays constrained) |
+| `isglobal` | integer | `0` / `1` | Open as global window (sticky across tags) |
+| `isoverlay` | integer | `0` / `1` | Make it always in top layer |
+| `isopensilent` | integer | `0` / `1` | Open without focus |
+| `istagsilent` | integer | `0` / `1` | Don't focus if client is not in current view tag |
+| `force_maximize` | integer | `0` / `1` (default 1) | The state of client default to maximized |
+| `ignore_maximize` | integer | `0` / `1` (default 1) | Don't handle maximize request from client |
+| `ignore_minimize` | integer | `0` / `1` (default 1) | Don't handle minimize request from client |
+| `force_tiled_state` | integer | `0` / `1` | Deceive the window into thinking it is tiling, so it better adheres to assigned dimensions |
+| `noopenmaximized` | integer | `0` / `1` | Window does not open as maximized mode |
+| `single_scratchpad` | integer | `0` / `1` (default 1) | Only show one out of named scratchpads or the normal scratchpad |
+| `allow_shortcuts_inhibit` | integer | `0` / `1` (default 1) | Allow shortcuts to be inhibited by clients |
+| `indleinhibit_when_focus` | integer | `0` / `1` (default 0) | Automatically keep idle inhibit active when this window is focused |
+
+### Geometry & Position
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `width` | integer | 0-9999 | Window width when it becomes a floating window |
+| `height` | integer | 0-9999 | Window height when it becomes a floating window |
+| `offsetx` | integer | -999-999 | X offset from center (%), 100 is the edge of screen with outer gap |
+| `offsety` | integer | -999-999 | Y offset from center (%), 100 is the edge of screen with outer gap |
+| `monitor` | string | Any | Assign to monitor by [monitor spec](/docs/configuration/monitors#monitor-spec-format) (name, make, model, or serial) |
+| `tags` | integer | 1-9 | Assign to specific tag |
+| `no_force_center` | integer | `0` / `1` | Window does not force center |
+| `isnosizehint` | integer | `0` / `1` | Don't use min size and max size for size hints |
+
+### Visuals & Decoration
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `noblur` | integer | `0` / `1` | Window does not have blur effect |
+| `isnoborder` | integer | `0` / `1` | Remove window border |
+| `isnoshadow` | integer | `0` / `1` | Not apply shadow |
+| `isnoradius` | integer | `0` / `1` | Not apply corner radius |
+| `isnoanimation` | integer | `0` / `1` | Not apply animation |
+| `focused_opacity` | integer | `0` / `1` | Window focused opacity |
+| `unfocused_opacity` | integer | `0` / `1` | Window unfocused opacity |
+| `allow_csd` | integer | `0` / `1` | Allow client side decoration |
+
+> **Tip:** For detailed visual effects configuration, see the [Window Effects](/docs/visuals/effects) page for blur, shadows, and opacity settings.
+
+### Layout & Scroller
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `scroller_proportion` | float | 0.1-1.0 | Set scroller proportion |
+| `scroller_proportion_single` | float | 0.1-1.0 | Set scroller auto adjust proportion when it is single window |
+
+> **Tip:** For comprehensive layout configuration, see the [Layouts](/docs/window-management/layouts) page for all layout options and detailed settings.
+
+### Animation
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `animation_type_open` | string | zoom, slide, fade, none | Set open animation |
+| `animation_type_close` | string | zoom, slide, fade, none | Set close animation |
+| `nofadein` | integer | `0` / `1` | Window ignores fade-in animation |
+| `nofadeout` | integer | `0` / `1` | Window ignores fade-out animation |
+
+> **Tip:** For detailed animation configuration, see the [Animations](/docs/visuals/animations) page for available types and settings.
+
+### Terminal & Swallowing
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `isterm` | integer | `0` / `1` | A new GUI window will replace the isterm window when it is opened |
+| `noswallow` | integer | `0` / `1` | The window will not replace the isterm window |
+
+### Global & Special Windows
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `globalkeybinding` | string | `[mod combination][-][key]` | Global keybinding (only works for Wayland apps) |
+| `isunglobal` | integer | `0` / `1` | Open as unmanaged global window (for desktop pets or camera windows) |
+| `isnamedscratchpad` | integer | `0` / `1` | 0: disable, 1: named scratchpad |
+
+> **Tip:** For scratchpad usage, see the [Scratchpad](/docs/window-management/scratchpad) page for detailed configuration examples.
+
+### Performance & Tearing
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `force_tearing` | integer | `0` / `1` | Set window to tearing state, refer to [Tearing](/docs/configuration/monitors#tearing-game-mode) |
+
+### Examples
+
+```ini
+# Set specific window size and position
+windowrule=width:1000,height:900,appid:yesplaymusic,title:Demons
+
+# Global keybindings for OBS Studio
+windowrule=globalkeybinding:ctrl+alt-o,appid:com.obsproject.Studio
+windowrule=globalkeybinding:ctrl+alt+n,appid:com.obsproject.Studio
+windowrule=isopensilent:1,appid:com.obsproject.Studio
+
+# Force tearing for games
+windowrule=force_tearing:1,title:vkcube
+windowrule=force_tearing:1,title:Counter-Strike 2
+
+# Named scratchpad for file manager
+windowrule=isnamedscratchpad:1,width:1280,height:800,appid:st-yazi
+
+# Custom opacity for specific apps
+windowrule=focused_opacity:0.8,appid:firefox
+windowrule=unfocused_opacity:0.6,appid:foot
+
+# Disable blur for selection tools
+windowrule=noblur:1,appid:slurp
+
+# Position windows relative to screen center
+windowrule=offsetx:20,offsety:-30,width:800,height:600,appid:alacritty
+
+# Send to specific tag and monitor
+windowrule=tags:9,monitor:HDMI-A-1,appid:discord
+
+# Terminal swallowing setup
+windowrule=isterm:1,appid:st
+windowrule=noswallow:1,appid:foot
+
+# Disable client-side decorations
+windowrule=allow_csd:1,appid:firefox
+
+# Unmanaged global window (desktop pets, camera)
+windowrule=isunglobal:1,appid:cheese
+
+# Named scratchpad toggle
+bind=alt,h,toggle_named_scratchpad,st-yazi,none,st -c st-yazi -e yazi
+```
+
+---
+
+## Tag Rules
+
+You can set all parameters in one line. If only `id` is set, the rule is followed when the id matches. If any of `monitor_name`, `monitor_make`, `monitor_model`, or `monitor_serial` are set, the rule is followed only if **all** of the set monitor fields match.
+
+> **Warning:** Layouts set in tag rules have a higher priority than monitor rule layouts.
+
+**Format:**
+
+```ini
+tagrule=id:Values,Parameter:Values,Parameter:Values
+tagrule=id:Values,monitor_name:eDP-1,Parameter:Values,Parameter:Values
+tagrule=id:Values,monitor_make:xxx,monitor_model:xxx,Parameter:Values
+```
+
+> **Tip:** See [Layouts](/docs/window-management/layouts#supported-layouts) for detailed descriptions of each layout type.
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `id` | integer | 0-9 | Match by tag id, 0 means the ~0 tag |
+| `monitor_name` | string | monitor name | Match by monitor name |
+| `monitor_make` | string | monitor make | Match by monitor manufacturer |
+| `monitor_model` | string | monitor model | Match by monitor model |
+| `monitor_serial` | string | monitor serial | Match by monitor serial number |
+| `layout_name` | string | layout name | Layout name to set |
+| `no_render_border` | integer | `0` / `1` | Disable render border |
+| `no_hide` | integer | `0` / `1` | Not hide even if the tag is empty |
+| `nmaster` | integer | 0, 99 | Number of master windows |
+| `mfact` | float | 0.1–0.9 | Master area factor |
+
+### Examples
+
+```ini
+# Set layout for specific tags
+tagrule=id:1,layout_name:scroller
+tagrule=id:2,layout_name:scroller
+
+# Limit to specific monitor
+tagrule=id:1,monitor_name:eDP-1,layout_name:scroller
+tagrule=id:2,monitor_name:eDP-1,layout_name:scroller
+
+# Persistent tags (1-4) with layout assignment
+tagrule=id:1,no_hide:1,layout_name:scroller
+tagrule=id:2,no_hide:1,layout_name:scroller
+tagrule=id:3,monitor_name:eDP-1,no_hide:1,layout_name:scroller
+tagrule=id:4,monitor_name:eDP-1,no_hide:1,layout_name:scroller
+
+# Advanced tag configuration with master layout settings
+tagrule=id:5,layout_name:tile,nmaster:2,mfact:0.6
+tagrule=id:6,monitor_name:HDMI-A-1,layout_name:monocle,no_render_border:1
+```
+
+> **Tip:** For Waybar configuration with persistent tags, see [Status Bar](/docs/visuals/status-bar) documentation.
+
+---
+
+## Layer Rules
+
+You can set all parameters in one line. Target "layer shell" surfaces like status bars (`waybar`), launchers (`rofi`), or notification daemons.
+
+**Format:**
+
+```ini
+layerrule=layer_name:Values,Parameter:Values,Parameter:Values
+```
+
+> **Tip:** You can use `mmsg -e` to get the last open layer name for debugging.
+
+| Parameter | Type | Values | Description |
+| :--- | :--- | :--- | :--- |
+| `layer_name` | string | layer name | Match name of layer, supports regex |
+| `animation_type_open` | string | slide, zoom, fade, none | Set open animation |
+| `animation_type_close` | string | slide, zoom, fade, none | Set close animation |
+| `noblur` | integer | `0` / `1` | Disable blur |
+| `noanim` | integer | `0` / `1` | Disable layer animation |
+| `noshadow` | integer | `0` / `1` | Disable layer shadow |
+
+> **Tip:** For animation types, see [Animations](/docs/visuals/animations#animation-types). For visual effects, see [Window Effects](/docs/visuals/effects).
+
+### Examples
+
+```ini
+# No blur or animation for slurp selection layer (avoids occlusion and ghosting in screenshots)
+layerrule=noanim:1,noblur:1,layer_name:selection
+
+# Zoom animation for Rofi with multiple parameters
+layerrule=animation_type_open:zoom,noanim:0,layer_name:rofi
+
+# Disable animations and shadows for notification daemon
+layerrule=noanim:1,noshadow:1,layer_name:swaync
+
+# Multiple effects for launcher
+layerrule=animation_type_open:slide,animation_type_close:fade,noblur:1,layer_name:wofi
+```

docs/window-management/scratchpad.md

@@ -0,0 +1,73 @@
+---
+title: Scratchpad
+description: Manage hidden "scratchpad" windows for quick access.
+---
+
+mangowm supports two types of scratchpads: the standard pool (Sway-like) and named scratchpads.
+
+## Standard Scratchpad
+
+Any window can be sent to the "scratchpad" pile, which hides it. You can then cycle through them.
+
+**Keybindings:**
+
+```ini
+# Send current window to scratchpad
+bind=SUPER,i,minimized
+
+# Toggle (show/hide) the scratchpad
+bind=ALT,z,toggle_scratchpad
+
+# Retrieve window from scratchpad (restore)
+bind=SUPER+SHIFT,i,restore_minimized
+```
+
+---
+
+## Named Scratchpad
+
+Named scratchpads are bound to specific keys and applications. When triggered, mangowm will either launch the app (if not running) or toggle its visibility.
+
+**1. Define the Window Rule**
+
+You must identify the app using a unique `appid` or `title` and mark it as a named scratchpad. The application must support setting a custom appid or title at launch. Common examples:
+
+- `st -c my-appid` — sets the appid
+- `kitty -T my-title` — sets the window title
+- `foot --app-id my-appid` — sets the appid
+
+Use `none` as a placeholder when you only want to match by one field.
+
+```ini
+# Match by appid
+windowrule=isnamedscratchpad:1,width:1280,height:800,appid:st-yazi
+
+# Match by title
+windowrule=isnamedscratchpad:1,width:1000,height:700,title:kitty-scratch
+```
+
+**2. Bind the Toggle Key**
+
+Format: `bind=MOD,KEY,toggle_named_scratchpad,appid,title,command`
+
+Use `none` for whichever field you are not matching on.
+
+```ini
+# Match by appid: launch 'st' with class 'st-yazi' running 'yazi'
+bind=alt,h,toggle_named_scratchpad,st-yazi,none,st -c st-yazi -e yazi
+
+# Match by title: launch 'kitty' with window title 'kitty-scratch'
+bind=alt,k,toggle_named_scratchpad,none,kitty-scratch,kitty -T kitty-scratch
+```
+
+---
+
+## Appearance
+
+You can customize the size of scratchpad windows relative to the screen.
+
+```ini
+scratchpad_width_ratio=0.8
+scratchpad_height_ratio=0.9
+scratchpadcolor=0x516c93ff
+```