mirrors/maomaowm
1
0
Fork 0
mirror of https://github.com/DreamMaoMao/maomaowm.git synced 2026-07-10 11:04:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

feat(docs): use workflow for version docs generation

Browse source
This commit is contained in:
xtheeq 2026-05-26 18:25:50 +05:30
parent 887a50a54e
commit 8765f9b7c5
97 changed files with 53 additions and 6826 deletions
Download patch file Download diff file Expand all files Collapse all files

7
.github/scripts/sync-wiki.py vendored
View file

@ -5,7 +5,6 @@ from pathlib import Path
DOCS_DIR = Path("docs") DOCS_DIR = Path("docs")
WIKI_DIR = Path("wiki-temp") WIKI_DIR = Path("wiki-temp")
LATEST_DIR = DOCS_DIR / "(git)"
FRONTMATTER_RE = re.compile(r"\A---\s*\n.*?^---\s*\n", re.DOTALL | re.MULTILINE) FRONTMATTER_RE = re.compile(r"\A---\s*\n.*?^---\s*\n", re.DOTALL | re.MULTILINE)
DOCS_LINK_RE = re.compile(r"\[([^\]]+)\]\(/docs/(?:[^/)]+/)*([^/)#]+)(#[^)]+)?\)") DOCS_LINK_RE = re.compile(r"\[([^\]]+)\]\(/docs/(?:[^/)]+/)*([^/)#]+)(#[^)]+)?\)")
@ -21,10 +20,10 @@ def collect_all_files() -> list[tuple[Path, str]]:
return [directory / f"{p}.md" for p in data.get("pages", []) if (directory / f"{p}.md").exists()] return [directory / f"{p}.md" for p in data.get("pages", []) if (directory / f"{p}.md").exists()]
return sorted(directory.glob("*.md")) return sorted(directory.glob("*.md"))
for src in from_dir(LATEST_DIR): for src in from_dir(DOCS_DIR):
files.append((src, "Home" if src.stem == "index" else src.stem)) files.append((src, "Home" if src.stem == "index" else src.stem))
for subdir in sorted(LATEST_DIR.iterdir()): for subdir in sorted(DOCS_DIR.iterdir()):
if subdir.is_dir(): if subdir.is_dir():
for src in from_dir(subdir): for src in from_dir(subdir):
files.append((src, src.stem)) files.append((src, src.stem))
@ -45,7 +44,7 @@ def main() -> None:
lines: list[str] = [] lines: list[str] = []
current_section = None current_section = None
for src, dest_name in files: for src, dest_name in files:
section = "General" if src.parent == LATEST_DIR else src.parent.name.replace("-", " ").title() section = "General" if src.parent == DOCS_DIR else src.parent.name.replace("-", " ").title()
if section != current_section: if section != current_section:
if current_section is not None: if current_section is not None:
lines.append("") lines.append("")

4
.github/workflows/generate-nix-options-docs.yml vendored
View file

@ -53,11 +53,11 @@ jobs:
python3 ./.github/scripts/generate-nix-options-docs.py \ python3 ./.github/scripts/generate-nix-options-docs.py \
/tmp/nixos-raw.md \ /tmp/nixos-raw.md \
/tmp/hm-raw.md \ /tmp/hm-raw.md \
'docs/(git)/nix-options.md' 'docs/nix-options.md'
- name: Auto-commit changes - name: Auto-commit changes
uses: stefanzweifel/git-auto-commit-action@v5 uses: stefanzweifel/git-auto-commit-action@v5
with: with:
commit_message: "docs: auto-generate Nix module options" commit_message: "docs: auto-generate Nix module options"
file_pattern: 'docs/**/nix-options.md' file_pattern: 'docs/nix-options.md'
branch: ${{ github.head_ref }} branch: ${{ github.head_ref }}

31
.github/workflows/sync-website.yml vendored
View file

@ -17,9 +17,11 @@ jobs:
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
with: with:
fetch-depth: 1
token: ${{ github.token }} token: ${{ github.token }}
- name: Fetch tags for versioned docs
run: git fetch origin --tags --depth=1
- name: Checkout website - name: Checkout website
uses: actions/checkout@v4 uses: actions/checkout@v4
with: with:
@ -30,8 +32,31 @@ jobs:
- name: Sync docs - name: Sync docs
run: | run: |
rm -rf website/apps/web/content/docs TARGET=website/apps/web/content/docs
cp -r docs website/apps/web/content/docs rm -rf "$TARGET"
mkdir -p "$TARGET"
# Copy current docs as "(git)"
cp -r docs "$TARGET/(git)"
# Generate versioned docs from last 2 semver tags
tags=$(git tag --sort=-v:refname | grep '^v\?[0-9]\+\.[0-9]\+\.[0-9]\+$' | head -2)
for tag in $tags; do
git worktree add /tmp/docs-"$tag" "$tag" || continue
if [ -d "/tmp/docs-$tag/docs" ]; then
name="v${tag#v}"
cp -r "/tmp/docs-$tag/docs" "$TARGET/$name"
fi
git worktree remove /tmp/docs-"$tag"
done
# Generate root version index
{
echo "(git)"
for tag in $tags; do
echo "v${tag#v}"
done
} | jq -Rn '[inputs | select(length > 0)] | {pages: .}' > "$TARGET/meta.json"
- name: Commit and push - name: Commit and push
working-directory: website working-directory: website

22
docs/(git)/meta.json
View file

@ -1,22 +0,0 @@
{
"title": "git (latest)",
"description": "Latest development",
"root": true,
"pages": [
"---Getting Started---",
"index",
"installation",
"quick-start",
"---Configuration---",
"configuration",
"visuals",
"window-management",
"bindings",
"---Examples---",
"screenshot",
"---Reference---",
"nix-options",
"ipc",
"faq"
]
}

0
docs/(git)/bindings/index.mdx → docs/bindings/index.mdx
View file

0
docs/(git)/bindings/keys.md → docs/bindings/keys.md
View file

0
docs/(git)/bindings/meta.json → docs/bindings/meta.json
View file

0
docs/(git)/bindings/mouse-gestures.md → docs/bindings/mouse-gestures.md
View file

0
docs/(git)/configuration/basics.md → docs/configuration/basics.md
View file

0
docs/(git)/configuration/index.mdx → docs/configuration/index.mdx
View file

0
docs/(git)/configuration/input.md → docs/configuration/input.md
View file

0
docs/(git)/configuration/meta.json → docs/configuration/meta.json
View file

0
docs/(git)/configuration/miscellaneous.md → docs/configuration/miscellaneous.md
View file

0
docs/(git)/configuration/monitors.md → docs/configuration/monitors.md
View file

0
docs/(git)/configuration/xdg-portals.md → docs/configuration/xdg-portals.md
View file

0
docs/(git)/faq.md → docs/faq.md
View file

0
docs/(git)/index.md → docs/index.md
View file

0
docs/(git)/installation.md → docs/installation.md
View file

0
docs/(git)/ipc.md → docs/ipc.md
View file

21
docs/meta.json
View file

@ -1,3 +1,22 @@
{ {
"pages": ["(git)", "v0.13.1", "v0.13.0"] "title": "git (latest)",
"description": "Latest development",
"root": true,
"pages": [
"---Getting Started---",
"index",
"installation",
"quick-start",
"---Configuration---",
"configuration",
"visuals",
"window-management",
"bindings",
"---Examples---",
"screenshot",
"---Reference---",
"nix-options",
"ipc",
"faq"
]
} }

0
docs/(git)/nix-options.md → docs/nix-options.md
View file

0
docs/(git)/quick-start.md → docs/quick-start.md
View file

0
docs/(git)/screenshot.md → docs/screenshot.md
View file

15
docs/v0.13.0/bindings/index.mdx
View file

@ -1,15 +0,0 @@
---
title: Bindings & Input
description: Keybindings, mouse gestures, and input devices.
icon: Keyboard
---
Configure how you interact with mangowm using flexible keybindings and input options.
<Cards>
<Card href="/docs/bindings/keys" title="Key Bindings" description="Keyboard shortcuts and modes" />
<Card href="/docs/bindings/mouse-gestures" title="Mouse Gestures" description="Touchpad and mouse gestures" />
</Cards>

216
docs/v0.13.0/bindings/keys.md
View file

@ -1,216 +0,0 @@
---
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. |
| `toggle_all_floating` | - | Toggle all visible clients 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. |
| `dwindle_toggle_split_direction` | - | Toggle split direction in dwindle layout. |
### 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
```
#### Playback
Requires: `playerctl`
```ini
bind=NONE,XF86AudioNext,spawn,playerctl next
bind=NONE,XF86AudioPrev,spawn,playerctl previous
bind=NONE,XF86AudioPlay,spawn,playerctl play-pause
```
### 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. |

4
docs/v0.13.0/bindings/meta.json
View file

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

116
docs/v0.13.0/bindings/mouse-gestures.md
View file

@ -1,116 +0,0 @@
---
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
```

87
docs/v0.13.0/configuration/basics.md
View file

@ -1,87 +0,0 @@
---
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 -c /path/to/config.conf -p
```
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=QT_IM_MODULES,wayland;fcitx
env=XMODIFIERS,@im=fcitx
```
## 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
```

21
docs/v0.13.0/configuration/index.mdx
View file

@ -1,21 +0,0 @@
---
title: Configuration
description: Configure mangowm with config files, environment variables, and autostart.
icon: Settings
---
Configure mangowm through config files, environment variables, and autostart.
<Cards>
<Card href="/docs/configuration/basics" title="Basics" description="Config files, env vars, exec-once, exec" />
<Card href="/docs/configuration/monitors" title="Monitors" description="Monitor settings and resolution" />
<Card href="/docs/configuration/input" title="Input" description="Keyboard, mouse, and touchpad" />
<Card href="/docs/configuration/xdg-portals" title="XDG Portals" description="File pickers and notifications" />
<Card href="/docs/configuration/miscellaneous" title="Miscellaneous" description="Additional options" />
</Cards>

161
docs/v0.13.0/configuration/input.md
View file

@ -1,161 +0,0 @@
---
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
```
---
### Mouse Settings
Configuration for external mice.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `mouse_natural_scrolling` | `0` | Invert scrolling direction. |
| `mouse_accel_profile` | `2` | `0` (None), `1` (Flat), `2` (Adaptive). |
| `mouse_accel_speed` | `0.0` | Speed adjustment (-1.0 to 1.0). |
| `left_handed` | `0` | Swap left and right buttons. |
| `axis_scroll_factor` | `1.0` | Scroll factor for axis scroll speed (0.1–10.0). |
---
### 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). |
| `trackpad_accel_profile` | `2` | `0` (None), `1` (Flat), `2` (Adaptive). |
| `trackpad_accel_speed` | `0.0` | Speed adjustment (-1.0 to 1.0). |
| `scroll_button` | `274` | The mouse button that use for scrolling(272 to 279).
| `scroll_method` | `1` | `1` (Two-finger), `2` (Edge), `4` (Button). |
| `click_method` | `1` | `1` (Button areas), `2` (Clickfinger). |
| `send_events_mode` | `0` | `0` (Enabled), `1` (Disabled), `2` (Disabled on external mouse). |
| `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 when use gesture. |
| `button_map` | `0` | `0` (Left/right/middle), `1` (Left/middle/right). |
| `trackpad_scroll_factor` | `1.0` | Scroll factor for trackpad scroll speed (0.1–10.0). |
---
**Detailed descriptions:**
- `scroll_button` values:
- `272` — Left button.
- `273` — Right button.
- `274` — Middle button.
- `275` — Side button.
- `276` — Extra button.
- `277` — Forward button.
- `278` — Back button.
- `279` — Task button.
- `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.
- `mouse_accel_profile` or `trackpad_scroll_profile` values:
- `0` — No acceleration.
- `1` — Flat: no dynamic acceleration. Pointer speed = original input speed × (1 + `mouse_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.
---
---
## 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=QT_IM_MODULES,wayland;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
```

4
docs/v0.13.0/configuration/meta.json
View file

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

50
docs/v0.13.0/configuration/miscellaneous.md
View file

@ -1,50 +0,0 @@
---
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_tile_small` | `1` | Allow dragging a tiled window temporarily to small size.|
| `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. |
## 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. |
## 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. |

276
docs/v0.13.0/configuration/monitors.md
View file

@ -1,276 +0,0 @@
---
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.
> **Note:** that "name" is a regular expression. If you want an exact match, you need to add `^` and `$` to the beginning and end of the expression, for example, `^eDP-1$` matches exactly the string `eDP-1`.
### 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-once=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.

76
docs/v0.13.0/configuration/xdg-portals.md
View file

@ -1,76 +0,0 @@
---
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.

100
docs/v0.13.0/faq.md
View file

@ -1,100 +0,0 @@
---
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.
```ini
syncobj_enable=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
```

42
docs/v0.13.0/index.md
View file

@ -1,42 +0,0 @@
---
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.
- **[mwc](https://github.com/nikoloc/mwc)** — 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.

308
docs/v0.13.0/installation.md
View file

@ -1,308 +0,0 @@
---
title: Installation
description: Install mangowm on AerynOS, 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.
---
### AerynOS
mangowm is available in the **AerynOS package repository**.
You can install it using the `moss` package manager:
```bash
sudo moss install mangowm
```
---
### 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. **Start mango on login**
The following are common examples. Refer to the official NixOS documentation for full configuration options.
**Option A — greetd:** Autologin on first start; login screen after logout.
```nix
services.greetd = {
enable = true;
settings = {
initial_session = {
command = "mango";
user = "your-username"; # auto-login on first start, no password required
};
default_session = {
command = "${pkgs.greetd.tuigreet}/bin/tuigreet --cmd mango";
user = "greeter";
};
};
};
```
**Option B — Display manager autologin:** Autologin via an existing display manager (e.g. SDDM, GDM). [`addLoginEntry`](/docs/nix-options#addloginentry) (default: `true`) automatically registers mango as a session.
```nix
services.displayManager = {
defaultSession = "mango"; # derived from mango.desktop filename
autoLogin = {
enable = true;
user = "your-username";
};
};
```
**Option C — getty autologin:** No login screen, boots directly into mango on TTY1.
For bash/zsh:
```nix
services.getty.autologinUser = "your-username";
environment.loginShellInit = ''
[ "$(tty)" = /dev/tty1 ] && exec mango
'';
```
For fish:
```nix
services.getty.autologinUser = "your-username";
programs.fish.loginShellInit = ''
if test (tty) = /dev/tty1
exec mango
end
'';
```
5. **All available options**
See [Nix Module Options](/docs/nix-options) for the full list of NixOS and Home Manager options.
---
### PikaOS
mangowm is available in the **PikaOS package repository**.
You can install it using the `pikman` package manager:
```bash
pikman install mangowm
```
---
## 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:
>
> - `wayland`
> - `wayland-protocols`
> - `libinput`
> - `libdrm`
> - `libxkbcommon`
> - `pixman`
> - `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.3 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
```

154
docs/v0.13.0/ipc.md
View file

@ -1,154 +0,0 @@
---
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), `DW` (Dwindle).
```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

22
docs/v0.13.0/meta.json
View file

@ -1,22 +0,0 @@
{
"title": "v0.13.0",
"description": "v0.13.0 release",
"root": true,
"pages": [
"---Getting Started---",
"index",
"installation",
"quick-start",
"---Configuration---",
"configuration",
"visuals",
"window-management",
"bindings",
"---Examples---",
"screenshot",
"---Reference---",
"nix-options",
"ipc",
"faq"
]
}

519
docs/v0.13.0/nix-options.md
View file

@ -1,519 +0,0 @@
---
title: Nix Module Options
description: NixOS and Home Manager configuration options for mangowm.
---
> **Note:** This document is automatically generated from the Nix module source code.
## NixOS
**System-level options via `programs.mango`.**
### enable
Whether to enable mango, a wayland compositor based on dwl\.
*Type:*
boolean
*Default:*
```nix
false
```
*Example:*
```nix
true
```
*Declared by:*
- [\<mango/nix/nixos-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix)
### package
The mango package to use
*Type:*
package
*Default:*
```nix
<derivation mango-nightly>
```
*Declared by:*
- [\<mango/nix/nixos-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix)
### addLoginEntry
Whether to add a login entry to the display manager for mango\. Only has effect if a display manager is configured (e\.g\. SDDM, GDM via ` services.displayManager `)\.
*Type:*
boolean
*Default:*
```nix
true
```
*Declared by:*
- [\<mango/nix/nixos-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix)
## Home Manager
**Configure mangowm declaratively via `wayland.windowManager.mango`.**
### enable
Whether to enable mangowm, a Wayland compositor based on dwl\.
*Type:*
boolean
*Default:*
```nix
false
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### package
The mango package to use
*Type:*
package
*Default:*
```nix
<derivation mango-nightly>
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### autostart_sh
Shell script to run on mango startup\. No shebang needed\.
When this option is set, the script will be written to
` ~/.config/mango/autostart.sh ` and an ` exec-once ` line
will be automatically added to the config to execute it\.
*Type:*
strings concatenated with “\\n”
*Default:*
```nix
""
```
*Example:*
```nix
''
waybar &
dunst &
''
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### bottomPrefixes
List of prefixes for attributes that should appear at the bottom of the config file\.
Attributes starting with these prefixes will be sorted to the end\.
*Type:*
list of string
*Default:*
```nix
[ ]
```
*Example:*
```nix
[
"source"
]
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### extraConfig
Extra configuration lines to add to ` ~/.config/mango/config.conf `\.
This is useful for advanced configurations that don’t fit the structured
settings format, or for options that aren’t yet supported by the module\.
*Type:*
strings concatenated with “\\n”
*Default:*
```nix
""
```
*Example:*
```nix
''
# Advanced config that doesn't fit structured format
special_option = 1
''
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### settings
Mango configuration written in Nix\. Entries with the same key
should be written as lists\. Variables and colors names should be
quoted\. See [https://mangowm\.github\.io/docs](https://mangowm\.github\.io/docs) for more examples\.
**Note:** This option uses a structured format that is converted to Mango’s
configuration syntax\. Nested attributes are flattened with underscore separators\.
For example: ` animation.duration_open = 400 ` becomes ` animation_duration_open = 400 `
Keymodes (submaps) are supported via the special ` keymode ` attribute\. Each keymode
is a nested attribute set under ` keymode ` that contains its own bindings\.
*Type:*
Mango configuration value
*Default:*
```nix
{ }
```
*Example:*
```nix
{
# Window effects
blur = 1;
blur_optimized = 1;
blur_params = {
radius = 5;
num_passes = 2;
};
border_radius = 6;
focused_opacity = 1.0;
# Animations - use underscores for multi-part keys
animations = 1;
animation_type_open = "slide";
animation_type_close = "slide";
animation_duration_open = 400;
animation_duration_close = 800;
# Or use nested attrs (will be flattened with underscores)
animation_curve = {
open = "0.46,1.0,0.29,1";
close = "0.08,0.92,0,1";
};
# Use lists for duplicate keys like bind and tagrule
bind = [
"SUPER,r,reload_config"
"Alt,space,spawn,rofi -show drun"
"Alt,Return,spawn,foot"
"ALT,R,setkeymode,resize" # Enter resize mode
];
tagrule = [
"id:1,layout_name:tile"
"id:2,layout_name:scroller"
];
# Keymodes (submaps) for modal keybindings
keymode = {
resize = {
bind = [
"NONE,Left,resizewin,-10,0"
"NONE,Escape,setkeymode,default"
];
};
};
}
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### systemd\.enable
Whether to enable ` mango-session.target ` on
mango startup\. This links to
` graphical-session.target `\.
Some important environment variables will be imported to systemd
and dbus user environment before reaching the target, including
- ` DISPLAY `
- ` WAYLAND_DISPLAY `
- ` XDG_CURRENT_DESKTOP `
- ` XDG_SESSION_TYPE `
- ` NIXOS_OZONE_WL `
You can extend this list using the ` systemd.variables ` option\.
*Type:*
boolean
*Default:*
```nix
true
```
*Example:*
```nix
false
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### systemd\.extraCommands
Extra commands to run after D-Bus activation\.
*Type:*
list of string
*Default:*
```nix
[
"systemctl --user reset-failed"
"systemctl --user start mango-session.target"
]
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### systemd\.variables
Environment variables imported into the systemd and D-Bus user environment\.
*Type:*
list of string
*Default:*
```nix
[
"DISPLAY"
"WAYLAND_DISPLAY"
"XDG_CURRENT_DESKTOP"
"XDG_SESSION_TYPE"
"NIXOS_OZONE_WL"
"XCURSOR_THEME"
"XCURSOR_SIZE"
]
```
*Example:*
```nix
[
"--all"
]
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### systemd\.xdgAutostart
Whether to enable autostart of applications using
` systemd-xdg-autostart-generator(8) `
\.
*Type:*
boolean
*Default:*
```nix
false
```
*Example:*
```nix
true
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### topPrefixes
List of prefixes for attributes that should appear at the top of the config file\.
Attributes starting with these prefixes will be sorted to the beginning\.
*Type:*
list of string
*Default:*
```nix
[ ]
```
*Example:*
```nix
[
"source"
]
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)

88
docs/v0.13.0/quick-start.md
View file

@ -1,88 +0,0 @@
---
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 | awww(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.

213
docs/v0.13.0/screenshot.md
View file

@ -1,213 +0,0 @@
---
title: Screenshots
description: Example screenshot keybindings and capture workflows for mangowm.
---
mangowm does not include a built-in screenshot tool. This keeps the compositor lean.
Instead, compose your own workflow from small Wayland utilities and bind them to keys;
| Tool | Purpose |
| :--- | :--- |
| [`grim`](https://github.com/emersion/grim) | Capture the screen or a region to a file |
| [`slurp`](https://github.com/emersion/slurp) | Interactively select a region for `grim` |
| [`wl-copy`](https://github.com/bugaevc/wl-clipboard) | Copy screenshots directly to the clipboard |
| [`satty`](https://github.com/gabm/Satty) | Annotate screenshots before saving |
| [`wayfreeze`](https://github.com/nicbk/wayfreeze) | Freeze the screen before capture |
Install the required with your package manager or from source.
`grim` writes to the file path you give it, but **will not create missing directories**. Create one first:
```bash
mkdir -p ~/Pictures/Screenshots
```
Any directory works. `~/Pictures/Screenshots/` is just a convention.
## Quick Binds
Short, single-step commands can be placed directly in `config.conf` with `spawn_shell`.
No script file needed.
### Fullscreen
Captures the entire display.
```ini
bind=NONE,Print,spawn_shell,grim $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png
```
### Region
Select an area with `slurp` before capturing.
```ini
bind=SHIFT,Print,spawn_shell,g=$(slurp -d) && [ -n "$g" ] && grim -g "$g" $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png
```
### Pointer
Captures the full screen including the cursor.
```ini
bind=ALT,Print,spawn_shell,grim -c $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png
```
### Clipboard
Captures to a temporary file and copies the image to the clipboard; no file is saved.
```ini
bind=CTRL,Print,spawn_shell,f=$(mktemp -t screenshot-XXXXXX.png) && grim "$f" && wl-copy < "$f" && rm -f "$f"
```
### Annotate
Captures and opens `satty` for drawing before saving.
```ini
bind=SUPER,Print,spawn_shell,f=$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png && grim "$f" && satty --filename "$f" --output-filename "$f" --actions-on-enter save-to-file --early-exit
```
## Script Binds
When a command involves multi-step logic, geometry parsing, FIFOs, or screen freezing,
move it into a script and invoke it with `spawn` instead of `spawn_shell`.
Create the scripts directory first:
```bash
mkdir -p ~/.config/mango/scripts/screenshot
```
### Window
Uses `mmsg` (ships with mango) to capture the focused window.
`~/.config/mango/scripts/screenshot/window.sh`:
```bash
#!/usr/bin/env bash
geometry=$(mmsg -x | awk '/x / {x=$3} /y / {y=$3} /width / {w=$3} /height / {h=$3} END {print x","y" "w"x"h}')
[ -z "$geometry" ] && exit 1
grim -g "$geometry" "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png"
```
```ini
bind=CTRL+SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/window.sh
```
### Freeze
Freezes the screen with `wayfreeze` before capturing.
`~/.config/mango/scripts/screenshot/freeze.sh`:
```bash
#!/usr/bin/env bash
pipe=$(mktemp -u).fifo
mkfifo "$pipe"
wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $pipe" &
wayfreeze_pid=$!
read -r < "$pipe"
grim "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png"
kill "$wayfreeze_pid" 2>/dev/null
rm -f "$pipe"
```
```ini
bind=CTRL+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/freeze.sh
```
### Freeze + Region
Freeze, then select a region with `slurp`. Cleans up on cancel.
`~/.config/mango/scripts/screenshot/freeze-region.sh`:
```bash
#!/usr/bin/env bash
pipe=$(mktemp -u).fifo
mkfifo "$pipe"
wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $pipe" &
wayfreeze_pid=$!
read -r < "$pipe"
geometry=$(slurp -d)
if [[ -z "$geometry" ]]; then
kill "$wayfreeze_pid" 2>/dev/null
rm -f "$pipe"
exit 1
fi
grim -g "$geometry" "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png"
kill "$wayfreeze_pid" 2>/dev/null
rm -f "$pipe"
```
```ini
bind=SHIFT+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/freeze-region.sh
```
Make all three scripts executable:
```bash
chmod +x ~/.config/mango/scripts/screenshot/*.sh
```
## All-in-One Script
Prefer fewer files? A single script with subcommands covers every mode above.
Place it in the same directory and use it in place of the individual scripts.
`~/.config/mango/scripts/screenshot/screenshot.sh`:
```bash
#!/usr/bin/env bash
set -euo pipefail
mkdir -p "$HOME/Pictures/Screenshots"
filepath="$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png"
case "${1:-fullscreen}" in
region)
g=$(slurp -d); [ -z "$g" ] && exit 1
grim -g "$g" "$filepath" ;;
window)
g=$(mmsg -x | awk '/x / {x=$3} /y / {y=$3} /width / {w=$3} /height / {h=$3} END {print x","y" "w"x"h}')
[ -z "$g" ] && exit 1
grim -g "$g" "$filepath" ;;
freeze)
p=$(mktemp -u).fifo; mkfifo "$p"
wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $p" & wp=$!
read -r < "$p"; grim "$filepath"
kill "$wp" 2>/dev/null; rm -f "$p" ;;
freeze-region)
p=$(mktemp -u).fifo; mkfifo "$p"
wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $p" & wp=$!
read -r < "$p"; g=$(slurp -d)
if [ -z "$g" ]; then kill "$wp" 2>/dev/null; rm -f "$p"; exit 1; fi
grim -g "$g" "$filepath"
kill "$wp" 2>/dev/null; rm -f "$p" ;;
annotate)
grim "$filepath"; satty --filename "$filepath" --output-filename "$filepath" --actions-on-enter save-to-file --early-exit ;;
*) grim "$filepath" ;;
esac
```
Make the script executable:
```bash
chmod +x ~/.config/mango/scripts/screenshot/screenshot.sh
```
Then add the binds to `config.conf`:
```ini
bind=NONE,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh fullscreen
bind=SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh region
bind=CTRL+SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh window
bind=CTRL+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh freeze
bind=SHIFT+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh freeze-region
bind=SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh annotate
```

108
docs/v0.13.0/visuals/animations.md
View file

@ -1,108 +0,0 @@
---
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.4
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) |

82
docs/v0.13.0/visuals/effects.md
View file

@ -1,82 +0,0 @@
---
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
```

19
docs/v0.13.0/visuals/index.mdx
View file

@ -1,19 +0,0 @@
---
title: Visuals
description: Customize borders, colors, effects, and animations.
icon: Palette
---
Customize the look of your desktop.
<Cards>
<Card href="/docs/visuals/theming" title="Theming" description="Borders, colors, and cursor" />
<Card href="/docs/visuals/status-bar" title="Status Bar" description="Built-in status bar" />
<Card href="/docs/visuals/effects" title="Effects" description="Blur, shadows, rounded corners" />
<Card href="/docs/visuals/animations" title="Animations" description="Window and tag animations" />
</Cards>

4
docs/v0.13.0/visuals/meta.json
View file

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

141
docs/v0.13.0/visuals/status-bar.md
View file

@ -1,141 +0,0 @@
---
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).

62
docs/v0.13.0/visuals/theming.md
View file

@ -1,62 +0,0 @@
---
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
# Drop shadow when dragging windows
dropcolor=0x8FBA7C55
# Split window border color in manual dwindle layout
splitcolor=0xEB441EFF
# 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
```

19
docs/v0.13.0/window-management/index.mdx
View file

@ -1,19 +0,0 @@
---
title: Window Management
description: Layouts, rules, and window behavior.
icon: LayoutGrid
---
Window management with layouts, rules, and scratchpad support.
<Cards>
<Card href="/docs/window-management/layouts" title="Layouts" description="Tile, scroller, monocle, grid, deck" />
<Card href="/docs/window-management/rules" title="Rules" description="Window rules and conditions" />
<Card href="/docs/window-management/overview" title="Overview" description="Window states and properties" />
<Card href="/docs/window-management/scratchpad" title="Scratchpad" description="Quick access to applications" />
</Cards>

133
docs/v0.13.0/window-management/layouts.md
View file

@ -1,133 +0,0 @@
---
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`
- `dwindle`
---
## 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
```
---
## Dwindle Layout
The Dwindle layout arranges windows as a binary tree of recursive splits. Each new window splits the focused window's container, producing a spiral-like tiling.
### Configuration
| Setting | Default | Description |
| :--- | :--- | :--- |
| `dwindle_split_ratio` | `0.5` | Ratio used for new splits (`0.05`–`0.95`). |
| `dwindle_smart_split` | `0` | Pick the split axis from the cursor's position inside the focused window. The new window appears on the cursor's side. |
| `dwindle_hsplit` | `1` | Side-by-side splits: where the new window goes. `0` = follow cursor, `1` = right, `2` = left. |
| `dwindle_vsplit` | `1` | Top/bottom splits: where the new window goes. `0` = follow cursor, `1` = below, `2` = above. |
| `dwindle_preserve_split` | `0` | Keep the sibling's split orientation when a window is closed. |
| `dwindle_smart_resize` | `0` | When dragging to resize, move the split toward the cursor regardless of which side was grabbed. |
| `dwindle_drop_simple_split` | `1` | Drag-to-tile drop preview. `1` = 2-zone preview matching `dwindle_split_ratio`, `0` = 4-quadrant preview. |
| `dwindle_manual_split` | `0` | Manually split windows mode. |
```ini
# Example dwindle configuration
dwindle_split_ratio=0.5
dwindle_smart_split=0
dwindle_hsplit=0
dwindle_vsplit=0
dwindle_preserve_split=0
dwindle_smart_resize=0
dwindle_drop_simple_split=1
```
---
## Switching Layouts
| Setting | Default | Description |
| :--- | :--- | :--- |
| `circle_layout` | - | A comma-separated list of layouts `switch_layout` cycles through,the value sample:`tile,scroller`. |
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
circle_layout=grid,scroller,tile
bind=SUPER,n,switch_layout
# Set specific layout
bind=SUPER,t,setlayout,tile
bind=SUPER,s,setlayout,scroller
```

4
docs/v0.13.0/window-management/meta.json
View file

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

29
docs/v0.13.0/window-management/overview.md
View file

@ -1,29 +0,0 @@
---
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.

250
docs/v0.13.0/window-management/rules.md
View file

@ -1,250 +0,0 @@
---
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_fakemaximize` | integer | `0` / `1` (default 1) | The state of client set to fake 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` | float | 0-9999 | Window width when it becomes a floating window,if the value below 1, it will be the percentage of the screen width,otherwise it will be the pixel value |
| `height` | float | 0-9999 | Window height when it becomes a floating window,if the value below 1, it will be the percentage of the screen height,otherwise it will be the pixel value |
| `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 |
| `open_as_floating` | integer | `0` / `1` | New open window will be floating|
| `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
```

73
docs/v0.13.0/window-management/scratchpad.md
View file

@ -1,73 +0,0 @@
---
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
```

15
docs/v0.13.1/bindings/index.mdx
View file

@ -1,15 +0,0 @@
---
title: Bindings & Input
description: Keybindings, mouse gestures, and input devices.
icon: Keyboard
---
Configure how you interact with mangowm using flexible keybindings and input options.
<Cards>
<Card href="/docs/bindings/keys" title="Key Bindings" description="Keyboard shortcuts and modes" />
<Card href="/docs/bindings/mouse-gestures" title="Mouse Gestures" description="Touchpad and mouse gestures" />
</Cards>

216
docs/v0.13.1/bindings/keys.md
View file

@ -1,216 +0,0 @@
---
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. |
| `toggle_all_floating` | - | Toggle all visible clients 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. |
| `dwindle_toggle_split_direction` | - | Toggle split direction in dwindle layout. |
### 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
```
#### Playback
Requires: `playerctl`
```ini
bind=NONE,XF86AudioNext,spawn,playerctl next
bind=NONE,XF86AudioPrev,spawn,playerctl previous
bind=NONE,XF86AudioPlay,spawn,playerctl play-pause
```
### 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. |

4
docs/v0.13.1/bindings/meta.json
View file

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

116
docs/v0.13.1/bindings/mouse-gestures.md
View file

@ -1,116 +0,0 @@
---
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
```

87
docs/v0.13.1/configuration/basics.md
View file

@ -1,87 +0,0 @@
---
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 -c /path/to/config.conf -p
```
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=QT_IM_MODULES,wayland;fcitx
env=XMODIFIERS,@im=fcitx
```
## 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
```

21
docs/v0.13.1/configuration/index.mdx
View file

@ -1,21 +0,0 @@
---
title: Configuration
description: Configure mangowm with config files, environment variables, and autostart.
icon: Settings
---
Configure mangowm through config files, environment variables, and autostart.
<Cards>
<Card href="/docs/configuration/basics" title="Basics" description="Config files, env vars, exec-once, exec" />
<Card href="/docs/configuration/monitors" title="Monitors" description="Monitor settings and resolution" />
<Card href="/docs/configuration/input" title="Input" description="Keyboard, mouse, and touchpad" />
<Card href="/docs/configuration/xdg-portals" title="XDG Portals" description="File pickers and notifications" />
<Card href="/docs/configuration/miscellaneous" title="Miscellaneous" description="Additional options" />
</Cards>

161
docs/v0.13.1/configuration/input.md
View file

@ -1,161 +0,0 @@
---
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
```
---
### Mouse Settings
Configuration for external mice.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `mouse_natural_scrolling` | `0` | Invert scrolling direction. |
| `mouse_accel_profile` | `2` | `0` (None), `1` (Flat), `2` (Adaptive). |
| `mouse_accel_speed` | `0.0` | Speed adjustment (-1.0 to 1.0). |
| `left_handed` | `0` | Swap left and right buttons. |
| `axis_scroll_factor` | `1.0` | Scroll factor for axis scroll speed (0.1–10.0). |
---
### 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). |
| `trackpad_accel_profile` | `2` | `0` (None), `1` (Flat), `2` (Adaptive). |
| `trackpad_accel_speed` | `0.0` | Speed adjustment (-1.0 to 1.0). |
| `scroll_button` | `274` | The mouse button that use for scrolling(272 to 279).
| `scroll_method` | `1` | `1` (Two-finger), `2` (Edge), `4` (Button). |
| `click_method` | `1` | `1` (Button areas), `2` (Clickfinger). |
| `send_events_mode` | `0` | `0` (Enabled), `1` (Disabled), `2` (Disabled on external mouse). |
| `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 when use gesture. |
| `button_map` | `0` | `0` (Left/right/middle), `1` (Left/middle/right). |
| `trackpad_scroll_factor` | `1.0` | Scroll factor for trackpad scroll speed (0.1–10.0). |
---
**Detailed descriptions:**
- `scroll_button` values:
- `272` — Left button.
- `273` — Right button.
- `274` — Middle button.
- `275` — Side button.
- `276` — Extra button.
- `277` — Forward button.
- `278` — Back button.
- `279` — Task button.
- `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.
- `mouse_accel_profile` or `trackpad_scroll_profile` values:
- `0` — No acceleration.
- `1` — Flat: no dynamic acceleration. Pointer speed = original input speed × (1 + `mouse_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.
---
---
## 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=QT_IM_MODULES,wayland;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
```

4
docs/v0.13.1/configuration/meta.json
View file

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

50
docs/v0.13.1/configuration/miscellaneous.md
View file

@ -1,50 +0,0 @@
---
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_tile_small` | `1` | Allow dragging a tiled window temporarily to small size.|
| `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. |
## 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. |
## 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. |

276
docs/v0.13.1/configuration/monitors.md
View file

@ -1,276 +0,0 @@
---
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.
> **Note:** that "name" is a regular expression. If you want an exact match, you need to add `^` and `$` to the beginning and end of the expression, for example, `^eDP-1$` matches exactly the string `eDP-1`.
### 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-once=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.

76
docs/v0.13.1/configuration/xdg-portals.md
View file

@ -1,76 +0,0 @@
---
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.

100
docs/v0.13.1/faq.md
View file

@ -1,100 +0,0 @@
---
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.
```ini
syncobj_enable=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
```

42
docs/v0.13.1/index.md
View file

@ -1,42 +0,0 @@
---
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.
- **[mwc](https://github.com/nikoloc/mwc)** — 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.

308
docs/v0.13.1/installation.md
View file

@ -1,308 +0,0 @@
---
title: Installation
description: Install mangowm on AerynOS, 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.
---
### AerynOS
mangowm is available in the **AerynOS package repository**.
You can install it using the `moss` package manager:
```bash
sudo moss install mangowm
```
---
### 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. **Start mango on login**
The following are common examples. Refer to the official NixOS documentation for full configuration options.
**Option A — greetd:** Autologin on first start; login screen after logout.
```nix
services.greetd = {
enable = true;
settings = {
initial_session = {
command = "mango";
user = "your-username"; # auto-login on first start, no password required
};
default_session = {
command = "${pkgs.greetd.tuigreet}/bin/tuigreet --cmd mango";
user = "greeter";
};
};
};
```
**Option B — Display manager autologin:** Autologin via an existing display manager (e.g. SDDM, GDM). [`addLoginEntry`](/docs/nix-options#addloginentry) (default: `true`) automatically registers mango as a session.
```nix
services.displayManager = {
defaultSession = "mango"; # derived from mango.desktop filename
autoLogin = {
enable = true;
user = "your-username";
};
};
```
**Option C — getty autologin:** No login screen, boots directly into mango on TTY1.
For bash/zsh:
```nix
services.getty.autologinUser = "your-username";
environment.loginShellInit = ''
[ "$(tty)" = /dev/tty1 ] && exec mango
'';
```
For fish:
```nix
services.getty.autologinUser = "your-username";
programs.fish.loginShellInit = ''
if test (tty) = /dev/tty1
exec mango
end
'';
```
5. **All available options**
See [Nix Module Options](/docs/nix-options) for the full list of NixOS and Home Manager options.
---
### PikaOS
mangowm is available in the **PikaOS package repository**.
You can install it using the `pikman` package manager:
```bash
pikman install mangowm
```
---
## 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:
>
> - `wayland`
> - `wayland-protocols`
> - `libinput`
> - `libdrm`
> - `libxkbcommon`
> - `pixman`
> - `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.3 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
```

154
docs/v0.13.1/ipc.md
View file

@ -1,154 +0,0 @@
---
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), `DW` (Dwindle), `F` (Fair), `VF` (Vertical Fair).
```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

22
docs/v0.13.1/meta.json
View file

@ -1,22 +0,0 @@
{
"title": "v0.13.1",
"description": "v0.13.1 release",
"root": true,
"pages": [
"---Getting Started---",
"index",
"installation",
"quick-start",
"---Configuration---",
"configuration",
"visuals",
"window-management",
"bindings",
"---Examples---",
"screenshot",
"---Reference---",
"nix-options",
"ipc",
"faq"
]
}

519
docs/v0.13.1/nix-options.md
View file

@ -1,519 +0,0 @@
---
title: Nix Module Options
description: NixOS and Home Manager configuration options for mangowm.
---
> **Note:** This document is automatically generated from the Nix module source code.
## NixOS
**System-level options via `programs.mango`.**
### enable
Whether to enable mango, a wayland compositor based on dwl\.
*Type:*
boolean
*Default:*
```nix
false
```
*Example:*
```nix
true
```
*Declared by:*
- [\<mango/nix/nixos-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix)
### package
The mango package to use
*Type:*
package
*Default:*
```nix
<derivation mango-nightly>
```
*Declared by:*
- [\<mango/nix/nixos-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix)
### addLoginEntry
Whether to add a login entry to the display manager for mango\. Only has effect if a display manager is configured (e\.g\. SDDM, GDM via ` services.displayManager `)\.
*Type:*
boolean
*Default:*
```nix
true
```
*Declared by:*
- [\<mango/nix/nixos-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix)
## Home Manager
**Configure mangowm declaratively via `wayland.windowManager.mango`.**
### enable
Whether to enable mangowm, a Wayland compositor based on dwl\.
*Type:*
boolean
*Default:*
```nix
false
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### package
The mango package to use
*Type:*
package
*Default:*
```nix
<derivation mango-nightly>
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### autostart_sh
Shell script to run on mango startup\. No shebang needed\.
When this option is set, the script will be written to
` ~/.config/mango/autostart.sh ` and an ` exec-once ` line
will be automatically added to the config to execute it\.
*Type:*
strings concatenated with “\\n”
*Default:*
```nix
""
```
*Example:*
```nix
''
waybar &
dunst &
''
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### bottomPrefixes
List of prefixes for attributes that should appear at the bottom of the config file\.
Attributes starting with these prefixes will be sorted to the end\.
*Type:*
list of string
*Default:*
```nix
[ ]
```
*Example:*
```nix
[
"source"
]
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### extraConfig
Extra configuration lines to add to ` ~/.config/mango/config.conf `\.
This is useful for advanced configurations that don’t fit the structured
settings format, or for options that aren’t yet supported by the module\.
*Type:*
strings concatenated with “\\n”
*Default:*
```nix
""
```
*Example:*
```nix
''
# Advanced config that doesn't fit structured format
special_option = 1
''
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### settings
Mango configuration written in Nix\. Entries with the same key
should be written as lists\. Variables and colors names should be
quoted\. See [https://mangowm\.github\.io/docs](https://mangowm\.github\.io/docs) for more examples\.
**Note:** This option uses a structured format that is converted to Mango’s
configuration syntax\. Nested attributes are flattened with underscore separators\.
For example: ` animation.duration_open = 400 ` becomes ` animation_duration_open = 400 `
Keymodes (submaps) are supported via the special ` keymode ` attribute\. Each keymode
is a nested attribute set under ` keymode ` that contains its own bindings\.
*Type:*
Mango configuration value
*Default:*
```nix
{ }
```
*Example:*
```nix
{
# Window effects
blur = 1;
blur_optimized = 1;
blur_params = {
radius = 5;
num_passes = 2;
};
border_radius = 6;
focused_opacity = 1.0;
# Animations - use underscores for multi-part keys
animations = 1;
animation_type_open = "slide";
animation_type_close = "slide";
animation_duration_open = 400;
animation_duration_close = 800;
# Or use nested attrs (will be flattened with underscores)
animation_curve = {
open = "0.46,1.0,0.29,1";
close = "0.08,0.92,0,1";
};
# Use lists for duplicate keys like bind and tagrule
bind = [
"SUPER,r,reload_config"
"Alt,space,spawn,rofi -show drun"
"Alt,Return,spawn,foot"
"ALT,R,setkeymode,resize" # Enter resize mode
];
tagrule = [
"id:1,layout_name:tile"
"id:2,layout_name:scroller"
];
# Keymodes (submaps) for modal keybindings
keymode = {
resize = {
bind = [
"NONE,Left,resizewin,-10,0"
"NONE,Escape,setkeymode,default"
];
};
};
}
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### systemd\.enable
Whether to enable ` mango-session.target ` on
mango startup\. This links to
` graphical-session.target `\.
Some important environment variables will be imported to systemd
and dbus user environment before reaching the target, including
- ` DISPLAY `
- ` WAYLAND_DISPLAY `
- ` XDG_CURRENT_DESKTOP `
- ` XDG_SESSION_TYPE `
- ` NIXOS_OZONE_WL `
You can extend this list using the ` systemd.variables ` option\.
*Type:*
boolean
*Default:*
```nix
true
```
*Example:*
```nix
false
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### systemd\.extraCommands
Extra commands to run after D-Bus activation\.
*Type:*
list of string
*Default:*
```nix
[
"systemctl --user reset-failed"
"systemctl --user start mango-session.target"
]
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### systemd\.variables
Environment variables imported into the systemd and D-Bus user environment\.
*Type:*
list of string
*Default:*
```nix
[
"DISPLAY"
"WAYLAND_DISPLAY"
"XDG_CURRENT_DESKTOP"
"XDG_SESSION_TYPE"
"NIXOS_OZONE_WL"
"XCURSOR_THEME"
"XCURSOR_SIZE"
]
```
*Example:*
```nix
[
"--all"
]
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### systemd\.xdgAutostart
Whether to enable autostart of applications using
` systemd-xdg-autostart-generator(8) `
\.
*Type:*
boolean
*Default:*
```nix
false
```
*Example:*
```nix
true
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)
### topPrefixes
List of prefixes for attributes that should appear at the top of the config file\.
Attributes starting with these prefixes will be sorted to the beginning\.
*Type:*
list of string
*Default:*
```nix
[ ]
```
*Example:*
```nix
[
"source"
]
```
*Declared by:*
- [\<mango/nix/hm-modules\.nix>](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix)

88
docs/v0.13.1/quick-start.md
View file

@ -1,88 +0,0 @@
---
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 | awww(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.

213
docs/v0.13.1/screenshot.md
View file

@ -1,213 +0,0 @@
---
title: Screenshots
description: Example screenshot keybindings and capture workflows for mangowm.
---
mangowm does not include a built-in screenshot tool. This keeps the compositor lean.
Instead, compose your own workflow from small Wayland utilities and bind them to keys;
| Tool | Purpose |
| :--- | :--- |
| [`grim`](https://github.com/emersion/grim) | Capture the screen or a region to a file |
| [`slurp`](https://github.com/emersion/slurp) | Interactively select a region for `grim` |
| [`wl-copy`](https://github.com/bugaevc/wl-clipboard) | Copy screenshots directly to the clipboard |
| [`satty`](https://github.com/gabm/Satty) | Annotate screenshots before saving |
| [`wayfreeze`](https://github.com/nicbk/wayfreeze) | Freeze the screen before capture |
Install the required with your package manager or from source.
`grim` writes to the file path you give it, but **will not create missing directories**. Create one first:
```bash
mkdir -p ~/Pictures/Screenshots
```
Any directory works. `~/Pictures/Screenshots/` is just a convention.
## Quick Binds
Short, single-step commands can be placed directly in `config.conf` with `spawn_shell`.
No script file needed.
### Fullscreen
Captures the entire display.
```ini
bind=NONE,Print,spawn_shell,grim $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png
```
### Region
Select an area with `slurp` before capturing.
```ini
bind=SHIFT,Print,spawn_shell,g=$(slurp -d) && [ -n "$g" ] && grim -g "$g" $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png
```
### Pointer
Captures the full screen including the cursor.
```ini
bind=ALT,Print,spawn_shell,grim -c $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png
```
### Clipboard
Captures to a temporary file and copies the image to the clipboard; no file is saved.
```ini
bind=CTRL,Print,spawn_shell,f=$(mktemp -t screenshot-XXXXXX.png) && grim "$f" && wl-copy < "$f" && rm -f "$f"
```
### Annotate
Captures and opens `satty` for drawing before saving.
```ini
bind=SUPER,Print,spawn_shell,f=$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png && grim "$f" && satty --filename "$f" --output-filename "$f" --actions-on-enter save-to-file --early-exit
```
## Script Binds
When a command involves multi-step logic, geometry parsing, FIFOs, or screen freezing,
move it into a script and invoke it with `spawn` instead of `spawn_shell`.
Create the scripts directory first:
```bash
mkdir -p ~/.config/mango/scripts/screenshot
```
### Window
Uses `mmsg` (ships with mango) to capture the focused window.
`~/.config/mango/scripts/screenshot/window.sh`:
```bash
#!/usr/bin/env bash
geometry=$(mmsg -x | awk '/x / {x=$3} /y / {y=$3} /width / {w=$3} /height / {h=$3} END {print x","y" "w"x"h}')
[ -z "$geometry" ] && exit 1
grim -g "$geometry" "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png"
```
```ini
bind=CTRL+SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/window.sh
```
### Freeze
Freezes the screen with `wayfreeze` before capturing.
`~/.config/mango/scripts/screenshot/freeze.sh`:
```bash
#!/usr/bin/env bash
pipe=$(mktemp -u).fifo
mkfifo "$pipe"
wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $pipe" &
wayfreeze_pid=$!
read -r < "$pipe"
grim "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png"
kill "$wayfreeze_pid" 2>/dev/null
rm -f "$pipe"
```
```ini
bind=CTRL+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/freeze.sh
```
### Freeze + Region
Freeze, then select a region with `slurp`. Cleans up on cancel.
`~/.config/mango/scripts/screenshot/freeze-region.sh`:
```bash
#!/usr/bin/env bash
pipe=$(mktemp -u).fifo
mkfifo "$pipe"
wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $pipe" &
wayfreeze_pid=$!
read -r < "$pipe"
geometry=$(slurp -d)
if [[ -z "$geometry" ]]; then
kill "$wayfreeze_pid" 2>/dev/null
rm -f "$pipe"
exit 1
fi
grim -g "$geometry" "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png"
kill "$wayfreeze_pid" 2>/dev/null
rm -f "$pipe"
```
```ini
bind=SHIFT+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/freeze-region.sh
```
Make all three scripts executable:
```bash
chmod +x ~/.config/mango/scripts/screenshot/*.sh
```
## All-in-One Script
Prefer fewer files? A single script with subcommands covers every mode above.
Place it in the same directory and use it in place of the individual scripts.
`~/.config/mango/scripts/screenshot/screenshot.sh`:
```bash
#!/usr/bin/env bash
set -euo pipefail
mkdir -p "$HOME/Pictures/Screenshots"
filepath="$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png"
case "${1:-fullscreen}" in
region)
g=$(slurp -d); [ -z "$g" ] && exit 1
grim -g "$g" "$filepath" ;;
window)
g=$(mmsg -x | awk '/x / {x=$3} /y / {y=$3} /width / {w=$3} /height / {h=$3} END {print x","y" "w"x"h}')
[ -z "$g" ] && exit 1
grim -g "$g" "$filepath" ;;
freeze)
p=$(mktemp -u).fifo; mkfifo "$p"
wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $p" & wp=$!
read -r < "$p"; grim "$filepath"
kill "$wp" 2>/dev/null; rm -f "$p" ;;
freeze-region)
p=$(mktemp -u).fifo; mkfifo "$p"
wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $p" & wp=$!
read -r < "$p"; g=$(slurp -d)
if [ -z "$g" ]; then kill "$wp" 2>/dev/null; rm -f "$p"; exit 1; fi
grim -g "$g" "$filepath"
kill "$wp" 2>/dev/null; rm -f "$p" ;;
annotate)
grim "$filepath"; satty --filename "$filepath" --output-filename "$filepath" --actions-on-enter save-to-file --early-exit ;;
*) grim "$filepath" ;;
esac
```
Make the script executable:
```bash
chmod +x ~/.config/mango/scripts/screenshot/screenshot.sh
```
Then add the binds to `config.conf`:
```ini
bind=NONE,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh fullscreen
bind=SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh region
bind=CTRL+SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh window
bind=CTRL+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh freeze
bind=SHIFT+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh freeze-region
bind=SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh annotate
```

108
docs/v0.13.1/visuals/animations.md
View file

@ -1,108 +0,0 @@
---
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.4
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) |

82
docs/v0.13.1/visuals/effects.md
View file

@ -1,82 +0,0 @@
---
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
```

19
docs/v0.13.1/visuals/index.mdx
View file

@ -1,19 +0,0 @@
---
title: Visuals
description: Customize borders, colors, effects, and animations.
icon: Palette
---
Customize the look of your desktop.
<Cards>
<Card href="/docs/visuals/theming" title="Theming" description="Borders, colors, and cursor" />
<Card href="/docs/visuals/status-bar" title="Status Bar" description="Built-in status bar" />
<Card href="/docs/visuals/effects" title="Effects" description="Blur, shadows, rounded corners" />
<Card href="/docs/visuals/animations" title="Animations" description="Window and tag animations" />
</Cards>

4
docs/v0.13.1/visuals/meta.json
View file

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

141
docs/v0.13.1/visuals/status-bar.md
View file

@ -1,141 +0,0 @@
---
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).

62
docs/v0.13.1/visuals/theming.md
View file

@ -1,62 +0,0 @@
---
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
# Drop shadow when dragging windows
dropcolor=0x8FBA7C55
# Split window border color in manual dwindle layout
splitcolor=0xEB441EFF
# 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
```

19
docs/v0.13.1/window-management/index.mdx
View file

@ -1,19 +0,0 @@
---
title: Window Management
description: Layouts, rules, and window behavior.
icon: LayoutGrid
---
Window management with layouts, rules, and scratchpad support.
<Cards>
<Card href="/docs/window-management/layouts" title="Layouts" description="Tile, scroller, monocle, grid, deck" />
<Card href="/docs/window-management/rules" title="Rules" description="Window rules and conditions" />
<Card href="/docs/window-management/overview" title="Overview" description="Window states and properties" />
<Card href="/docs/window-management/scratchpad" title="Scratchpad" description="Quick access to applications" />
</Cards>

135
docs/v0.13.1/window-management/layouts.md
View file

@ -1,135 +0,0 @@
---
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`
- `dwindle`
- `fair`
- `vertical_fair`
---
## 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
```
---
## Dwindle Layout
The Dwindle layout arranges windows as a binary tree of recursive splits. Each new window splits the focused window's container, producing a spiral-like tiling.
### Configuration
| Setting | Default | Description |
| :--- | :--- | :--- |
| `dwindle_split_ratio` | `0.5` | Ratio used for new splits (`0.05`–`0.95`). |
| `dwindle_smart_split` | `0` | Pick the split axis from the cursor's position inside the focused window. The new window appears on the cursor's side. |
| `dwindle_hsplit` | `1` | Side-by-side splits: where the new window goes. `0` = follow cursor, `1` = right, `2` = left. |
| `dwindle_vsplit` | `1` | Top/bottom splits: where the new window goes. `0` = follow cursor, `1` = below, `2` = above. |
| `dwindle_preserve_split` | `0` | Keep the sibling's split orientation when a window is closed. |
| `dwindle_smart_resize` | `0` | When dragging to resize, move the split toward the cursor regardless of which side was grabbed. |
| `dwindle_drop_simple_split` | `1` | Drag-to-tile drop preview. `1` = 2-zone preview matching `dwindle_split_ratio`, `0` = 4-quadrant preview. |
| `dwindle_manual_split` | `0` | Manually split windows mode. |
```ini
# Example dwindle configuration
dwindle_split_ratio=0.5
dwindle_smart_split=0
dwindle_hsplit=0
dwindle_vsplit=0
dwindle_preserve_split=0
dwindle_smart_resize=0
dwindle_drop_simple_split=1
```
---
## Switching Layouts
| Setting | Default | Description |
| :--- | :--- | :--- |
| `circle_layout` | - | A comma-separated list of layouts `switch_layout` cycles through,the value sample:`tile,scroller`. |
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
circle_layout=grid,scroller,tile
bind=SUPER,n,switch_layout
# Set specific layout
bind=SUPER,t,setlayout,tile
bind=SUPER,s,setlayout,scroller
```

4
docs/v0.13.1/window-management/meta.json
View file

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

29
docs/v0.13.1/window-management/overview.md
View file

@ -1,29 +0,0 @@
---
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.

250
docs/v0.13.1/window-management/rules.md
View file

@ -1,250 +0,0 @@
---
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_fakemaximize` | integer | `0` / `1` (default 1) | The state of client set to fake 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` | float | 0-9999 | Window width when it becomes a floating window,if the value below 1, it will be the percentage of the screen width,otherwise it will be the pixel value |
| `height` | float | 0-9999 | Window height when it becomes a floating window,if the value below 1, it will be the percentage of the screen height,otherwise it will be the pixel value |
| `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 |
| `open_as_floating` | integer | `0` / `1` | New open window will be floating|
| `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
```

73
docs/v0.13.1/window-management/scratchpad.md
View file

@ -1,73 +0,0 @@
---
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
```

0
docs/(git)/visuals/animations.md → docs/visuals/animations.md
View file

0
docs/(git)/visuals/effects.md → docs/visuals/effects.md
View file

0
docs/(git)/visuals/index.mdx → docs/visuals/index.mdx
View file

0
docs/(git)/visuals/meta.json → docs/visuals/meta.json
View file

0
docs/(git)/visuals/status-bar.md → docs/visuals/status-bar.md
View file

0
docs/(git)/visuals/theming.md → docs/visuals/theming.md
View file

0
docs/(git)/window-management/index.mdx → docs/window-management/index.mdx
View file

0
docs/(git)/window-management/layouts.md → docs/window-management/layouts.md
View file

0
docs/(git)/window-management/meta.json → docs/window-management/meta.json
View file

0
docs/(git)/window-management/overview.md → docs/window-management/overview.md
View file

0
docs/(git)/window-management/rules.md → docs/window-management/rules.md
View file

0
docs/(git)/window-management/scratchpad.md → docs/window-management/scratchpad.md
View file