mangowm/mango
0
0
Fork 0
mirror of https://github.com/mangowm/mango.git synced 2026-05-02 14:27:27 -07:00
Code Issues Packages Projects Releases Wiki Activity

feat: add docs and sync with wiki & website

Browse Source
This commit is contained in:
atheeq-rhxn
2026-03-12 10:31:29 +05:30
committed by DreamMaoMao
parent 73616f07c4
commit 595524f0b2
28 changed files with 2594 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/scripts/sync-wiki.py
+61
View File
@@ -0,0 +1,61 @@
#!/usr/bin/env python3
import json
import re
from pathlib import Path
DOCS_DIR = Path("docs")
WIKI_DIR = Path("wiki-temp")
FRONTMATTER_RE = re.compile(r"\A---\s*\n.*?^---\s*\n", re.DOTALL | re.MULTILINE)
DOCS_LINK_RE = re.compile(r"\[([^\]]+)\]\(/docs/(?:[^/)]+/)*([^/)#]+)(#[^)]+)?\)")
def collect_all_files() -> list[tuple[Path, str]]:
files = []
def from_dir(directory: Path) -> list[Path]:
meta = directory / "meta.json"
if meta.exists():
data = json.loads(meta.read_text())
return [directory / f"{p}.md" for p in data.get("pages", []) if (directory / f"{p}.md").exists()]
return sorted(directory.glob("*.md"))
for src in from_dir(DOCS_DIR):
files.append((src, "Home" if src.stem == "index" else src.stem))
for subdir in sorted(DOCS_DIR.iterdir()):
if subdir.is_dir():
for src in from_dir(subdir):
files.append((src, src.stem))
return files
def main() -> None:
files = collect_all_files()
contents = {src: src.read_text() for src, _ in files}
for src, dest_name in files:
text = FRONTMATTER_RE.sub("", contents[src], count=1).lstrip("\n")
text = DOCS_LINK_RE.sub(lambda m: f"[{m.group(1)}]({m.group(2)}{m.group(3) or ''})", text)
(WIKI_DIR / f"{dest_name}.md").write_text(text)
lines: list[str] = []
current_section = None
for src, dest_name in files:
section = "General" if src.parent == DOCS_DIR else src.parent.name.replace("-", " ").title()
if section != current_section:
if current_section is not None:
lines.append("")
lines.append(f"## {section}\n")
current_section = section
if dest_name != "Home":
title = dest_name.replace("-", " ").replace("_", " ").title()
lines.append(f"- [[{dest_name}|{title}]]")
(WIKI_DIR / "_Sidebar.md").write_text("\n".join(lines))
if __name__ == "__main__":
main()
.github/workflows/sync-website.yml
+42
View File
@@ -0,0 +1,42 @@
name: Sync website
on:
push:
branches: [main]
paths:
- docs/**
concurrency:
group: sync-website
cancel-in-progress: true
jobs:
sync-website:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 1
token: ${{ github.token }}
- name: Checkout website
uses: actions/checkout@v4
with:
repository: mangowm/mangowm.github.io
path: website
token: ${{ secrets.WEBSITE_SYNC_TOKEN }}
fetch-depth: 1
- name: Sync docs
run: |
rm -rf website/apps/web/content/docs
cp -r docs website/apps/web/content/docs
- name: Commit and push
working-directory: website
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add apps/web/content/docs
git diff --staged --quiet || git commit -m "sync from mango @ ${{ github.sha }}"
git push
.github/workflows/sync-wiki.yml
+40
View File
@@ -0,0 +1,40 @@
name: Sync wiki
on:
push:
branches: [main]
paths:
- docs/**
concurrency:
group: sync-wiki
cancel-in-progress: true
permissions:
contents: write
jobs:
sync-wiki:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Clone wiki
run: |
git clone --depth 1 \
https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.wiki.git \
wiki-temp
- name: Sync docs to wiki
run: |
find wiki-temp -not -path 'wiki-temp/.git*' -type f -delete
python3 .github/scripts/sync-wiki.py
- name: Commit and push
working-directory: wiki-temp
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add -A
git diff --staged --quiet || git commit -m "sync from ${{ github.sha }}"
git push
docs/bindings/keys.md
+204
View File
@@ -0,0 +1,204 @@
---
title: Key Bindings
description: Define keyboard shortcuts and modes.
---
## Syntax
Key bindings follow this format:
```ini
bind[flags]=MODIFIERS,KEY,COMMAND,PARAMETERS
```
- **Modifiers**: `SUPER`, `CTRL`, `ALT`, `SHIFT`, `NONE` (combine with `+`, e.g. `SUPER+CTRL+ALT`).
- **Key**: Key name (from `xev` or `wev`) or keycode (e.g., `code:24` for `q`).
> **Info:** `bind` automatically converts keysym to keycode for comparison. This makes it compatible with all keyboard layouts, but the matching may not always be precise. If a key combination doesn't work on your keyboard layout, use a keycode instead (e.g., `code:24` instead of `q`).
### Flags
- `l`: Works even when screen is locked.
- `s`: Uses keysym instead of keycode to bind.
- `r`: Triggers on key release instead of press.
- `p`: Pass key event to client.
**Examples:**
```ini
bind=SUPER,Q,killclient
bindl=SUPER,L,spawn,swaylock
# Using keycode instead of key name
bind=ALT,code:24,killclient
# Combining keycodes for modifiers and keys
bind=code:64,code:24,killclient
bind=code:64+code:133,code:24,killclient
# Bind with no modifier
bind=NONE,XF86MonBrightnessUp,spawn,brightnessctl set +5%
# Bind a modifier key itself as the trigger key
bind=alt,shift_l,switch_keyboard_layout
```
## Key Modes (Submaps)
You can divide key bindings into named modes. Rules:
1. Set `keymode=<name>` before a group of `bind` lines — those binds only apply in that mode.
2. If no `keymode` is set before a bind, it belongs to the `default` mode.
3. The special `common` keymode applies its binds **across all modes**.
Use `setkeymode` to switch modes, and `mmsg -b` to query the current mode.
```ini
# Binds in 'common' apply in every mode
keymode=common
bind=SUPER,r,reload_config
# Default mode bindings
keymode=default
bind=ALT,Return,spawn,foot
bind=SUPER,F,setkeymode,resize
# 'resize' mode bindings
keymode=resize
bind=NONE,Left,resizewin,-10,0
bind=NONE,Right,resizewin,+10,0
bind=NONE,Escape,setkeymode,default
```
### Single Modifier Key Binding
When binding a modifier key itself, use `NONE` for press and the modifier name for release:
```ini
# Trigger on press of Super key
bind=none,Super_L,spawn,rofi -show run
# Trigger on release of Super key
bindr=Super,Super_L,spawn,rofi -show run
```
## Dispatchers List
### Window Management
| Command | Param | Description |
| :--- | :--- | :--- |
| `killclient` | - | Close the focused window. |
| `togglefloating` | - | Toggle floating state. |
| `togglefullscreen` | - | Toggle fullscreen. |
| `togglefakefullscreen` | - | Toggle "fake" fullscreen (remains constrained). |
| `togglemaximizescreen` | - | Maximize window (keep decoration/bar). |
| `toggleglobal` | - | Pin window to all tags. |
| `toggle_render_border` | - | Toggle border rendering. |
| `centerwin` | - | Center the floating window. |
| `minimized` | - | Minimize window to scratchpad. |
| `restore_minimized` | - | Restore window from scratchpad. |
| `toggle_scratchpad` | - | Toggle scratchpad. |
| `toggle_named_scratchpad` | `appid,title,cmd` | Toggle named scratchpad. Launches app if not running, otherwise shows/hides it. |
### Focus & Movement
| Command | Param | Description |
| :--- | :--- | :--- |
| `focusdir` | `left/right/up/down` | Focus window in direction. |
| `focusstack` | `next/prev` | Cycle focus within the stack. |
| `focuslast` | - | Focus the previously active window. |
| `exchange_client` | `left/right/up/down` | Swap window with neighbor in direction. |
| `exchange_stack_client` | `next/prev` | Exchange window position in stack. |
| `zoom` | - | Swap focused window with Master. |
### Tags & Monitors
| Command | Param | Description |
| :--- | :--- | :--- |
| `view` | `-1/0/1-9` or `mask [,synctag]` | View tag. `-1` = previous tagset, `0` = all tags, `1-9` = specific tag, mask e.g. `1\|3\|5`. Optional `synctag` (0/1) syncs the action to all monitors. |
| `viewtoleft` | `[synctag]` | View previous tag. Optional `synctag` (0/1) syncs to all monitors. |
| `viewtoright` | `[synctag]` | View next tag. Optional `synctag` (0/1) syncs to all monitors. |
| `viewtoleft_have_client` | `[synctag]` | View left tag and focus client if present. Optional `synctag` (0/1). |
| `viewtoright_have_client` | `[synctag]` | View right tag and focus client if present. Optional `synctag` (0/1). |
| `viewcrossmon` | `tag,monitor_spec` | View specified tag on specified monitor. |
| `tag` | `1-9 [,synctag]` | Move window to tag. Optional `synctag` (0/1) syncs to all monitors. |
| `tagsilent` | `1-9` | Move window to tag without focusing it. |
| `tagtoleft` | `[synctag]` | Move window to left tag. Optional `synctag` (0/1). |
| `tagtoright` | `[synctag]` | Move window to right tag. Optional `synctag` (0/1). |
| `tagcrossmon` | `tag,monitor_spec` | Move window to specified tag on specified monitor. |
| `toggletag` | `0-9` | Toggle tag on window (0 means all tags). |
| `toggleview` | `1-9` | Toggle tag view. |
| `comboview` | `1-9` | View multi tags pressed simultaneously. |
| `focusmon` | `left/right/up/down/monitor_spec` | Focus monitor by direction or [monitor spec](/docs/configuration/monitors#monitor-spec-format). |
| `tagmon` | `left/right/up/down/monitor_spec,[keeptag]` | Move window to monitor by direction or [monitor spec](/docs/configuration/monitors#monitor-spec-format). `keeptag` is 0 or 1. |
### Layouts
| Command | Param | Description |
| :--- | :--- | :--- |
| `setlayout` | `name` | Switch to layout (e.g., `scroller`, `tile`). |
| `switch_layout` | - | Cycle through available layouts. |
| `incnmaster` | `+1/-1` | Increase/Decrease number of master windows. |
| `setmfact` | `+0.05` | Increase/Decrease master area size. |
| `set_proportion` | `float` | Set scroller window proportion (0.0–1.0). |
| `switch_proportion_preset` | - | Cycle proportion presets of scroller window. |
| `scroller_stack` | `left/right/up/down` | Move window inside/outside scroller stack by direction. |
| `incgaps` | `+/-value` | Adjust gap size. |
| `togglegaps` | - | Toggle gaps. |
### System
| Command | Param | Description |
| :--- | :--- | :--- |
| `spawn` | `cmd` | Execute a command. |
| `spawn_shell` | `cmd` | Execute shell command (supports pipes `\|`). |
| `spawn_on_empty` | `cmd,tagnumber` | Open command on empty tag. |
| `reload_config` | - | Hot-reload configuration. |
| `quit` | - | Exit mangowm. |
| `toggleoverview` | - | Toggle overview mode. |
| `create_virtual_output` | - | Create a headless monitor (for VNC/Sunshine). |
| `destroy_all_virtual_output` | - | Destroy all virtual monitors. |
| `toggleoverlay` | - | Toggle overlay state for the focused window. |
| `toggle_trackpad_enable` | - | Toggle trackpad enable. |
| `setkeymode` | `mode` | Set keymode. |
| `switch_keyboard_layout` | `[index]` | Switch keyboard layout. Optional index (0, 1, 2...) to switch to specific layout. |
| `setoption` | `key,value` | Set config option temporarily. |
| `disable_monitor` | `monitor_spec` | Shutdown monitor. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). |
| `enable_monitor` | `monitor_spec` | Power on monitor. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). |
| `toggle_monitor` | `monitor_spec` | Toggle monitor power. Accepts a [monitor spec](/docs/configuration/monitors#monitor-spec-format). |
### Media Controls
> **Warning:** Some keyboards don't send standard media keys. Run `wev` and press your key to check the exact key name.
#### Brightness
Requires: `brightnessctl`
```ini
bind=NONE,XF86MonBrightnessUp,spawn,brightnessctl s +2%
bind=SHIFT,XF86MonBrightnessUp,spawn,brightnessctl s 100%
bind=NONE,XF86MonBrightnessDown,spawn,brightnessctl s 2%-
bind=SHIFT,XF86MonBrightnessDown,spawn,brightnessctl s 1%
```
#### Volume
Requires: `wpctl` (WirePlumber)
```ini
bind=NONE,XF86AudioRaiseVolume,spawn,wpctl set-volume @DEFAULT_SINK@ 5%+
bind=NONE,XF86AudioLowerVolume,spawn,wpctl set-volume @DEFAULT_SINK@ 5%-
bind=NONE,XF86AudioMute,spawn,wpctl set-mute @DEFAULT_SINK@ toggle
bind=SHIFT,XF86AudioMute,spawn,wpctl set-mute @DEFAULT_SOURCE@ toggle
```
### Floating Window Movement
| Command | Param | Description |
| :--- | :--- | :--- |
| `smartmovewin` | `left/right/up/down` | Move floating window by snap distance. |
| `smartresizewin` | `left/right/up/down` | Resize floating window by snap distance. |
| `movewin` | `(x,y)` | Move floating window. |
| `resizewin` | `(width,height)` | Resize window. |
docs/bindings/meta.json
+4
View File
@@ -0,0 +1,4 @@
{
"title": "Bindings & Input",
"pages": ["keys", "mouse-gestures"]
}
docs/bindings/mouse-gestures.md
+116
View File
@@ -0,0 +1,116 @@
---
title: Mouse & Gestures
description: Configure mouse buttons, scrolling, gestures, and lid switches.
---
## Mouse Bindings
Assign actions to mouse button presses with optional modifier keys.
### Syntax
```ini
mousebind=MODIFIERS,BUTTON,COMMAND,PARAMETERS
```
- **Modifiers**: `SUPER`, `CTRL`, `ALT`, `SHIFT`, `NONE`. Combine with `+` (e.g., `SUPER+CTRL`)
- **Buttons**: `btn_left`, `btn_right`, `btn_middle`, `btn_side`, `btn_extra`, `btn_forward`, `btn_back`, `btn_task`
> **Warning:** When modifiers are set to `NONE`, only `btn_middle` works in normal mode. `btn_left` and `btn_right` only work in overview mode.
### Examples
```ini
# Window manipulation
mousebind=SUPER,btn_left,moveresize,curmove
mousebind=SUPER,btn_right,moveresize,curresize
mousebind=SUPER+CTRL,btn_right,killclient
# Overview mode (requires NONE modifier)
mousebind=NONE,btn_left,toggleoverview,-1
mousebind=NONE,btn_right,killclient,0
mousebind=NONE,btn_middle,togglemaximizescreen,0
```
---
## Axis Bindings
Map scroll wheel movements to actions for workspace and window navigation.
### Syntax
```ini
axisbind=MODIFIERS,DIRECTION,COMMAND,PARAMETERS
```
- **Direction**: `UP`, `DOWN`, `LEFT`, `RIGHT`
### Examples
```ini
axisbind=SUPER,UP,viewtoleft_have_client
axisbind=SUPER,DOWN,viewtoright_have_client
```
---
## Gesture Bindings
Enable touchpad swipe gestures for navigation and window management.
### Syntax
```ini
gesturebind=MODIFIERS,DIRECTION,FINGERS,COMMAND,PARAMETERS
```
- **Direction**: `up`, `down`, `left`, `right`
- **Fingers**: `3` or `4`
> **Info:** Gestures require proper touchpad configuration. See [Input Devices](/docs/configuration/input) for touchpad settings like `tap_to_click` and `disable_while_typing`.
### Examples
```ini
# 3-finger: Window focus
gesturebind=none,left,3,focusdir,left
gesturebind=none,right,3,focusdir,right
gesturebind=none,up,3,focusdir,up
gesturebind=none,down,3,focusdir,down
# 4-finger: Workspace navigation
gesturebind=none,left,4,viewtoleft_have_client
gesturebind=none,right,4,viewtoright_have_client
gesturebind=none,up,4,toggleoverview
gesturebind=none,down,4,toggleoverview
```
---
## Switch Bindings
Trigger actions on hardware events like laptop lid open/close.
### Syntax
```ini
switchbind=FOLD_STATE,COMMAND,PARAMETERS
```
- **Fold State**: `fold` (lid closed), `unfold` (lid opened)
> **Warning:** Disable system lid handling in `/etc/systemd/logind.conf`:
>
> ```ini
> HandleLidSwitch=ignore
> HandleLidSwitchExternalPower=ignore
> HandleLidSwitchDocked=ignore
> ```
### Examples
```ini
switchbind=fold,spawn,swaylock -f -c 000000
switchbind=unfold,spawn,wlr-dpms on
```
docs/configuration/basics.md
+87
View File
@@ -0,0 +1,87 @@
---
title: Basic Configuration
description: Learn how to configure mangowm files, environment variables, and autostart scripts.
---
## Configuration File
mangowm uses a simple configuration file format. By default, it looks for a configuration file in `~/.config/mango/`.
1. **Locate Default Config**
A fallback configuration is provided at `/etc/mango/config.conf`. You can use this as a reference.
2. **Create User Config**
Copy the default config to your local config directory to start customizing.
```bash
mkdir -p ~/.config/mango
cp /etc/mango/config.conf ~/.config/mango/config.conf
```
3. **Launch with Custom Config (Optional)**
If you prefer to keep your config elsewhere, you can launch mango with the `-c` flag.
```bash
mango -c /path/to/your_config.conf
```
### Sub-Configuration
To keep your configuration organized, you can split it into multiple files and include them using the `source` keyword.
```ini
# Import keybindings from a separate file
source=~/.config/mango/bind.conf
# Relative paths work too
source=./theme.conf
# Optional: ignore if file doesn't exist (useful for shared configs)
source-optional=~/.config/mango/optional.conf
```
### Validate Configuration
You can check your configuration for errors without starting mangowm:
```bash
mango -p /path/to/config.conf
```
Use with `source-optional` for shared configs across different setups.
## Environment Variables
You can define environment variables directly within your config file. These are set before the window manager fully initializes.
> **Warning:** Environment variables defined here will be **reset** every time you reload the configuration.
```ini
env=GTK_THEME,Adwaita:dark
env=XCURSOR_SIZE,24
```
## Autostart
mangowm can automatically run commands or scripts upon startup. There are two modes for execution:
| Command | Behavior | Usage Case |
| :--- | :--- | :--- |
| `exec-once` | Runs **only once** when mangowm starts. | Status bars, Wallpapers, Notification daemons |
| `exec` | Runs **every time** the config is reloaded. | Scripts that need to refresh settings |
### Example Setup
```ini
# Start the status bar once
exec-once=waybar
# Set wallpaper
exec-once=swaybg -i ~/.config/mango/wallpaper/room.png
# Reload a custom script on config change
exec=bash ~/.config/mango/reload-settings.sh
```
docs/configuration/input.md
+150
View File
@@ -0,0 +1,150 @@
---
title: Input Devices
description: Configure keyboard layouts, mouse sensitivity, and touchpad gestures.
---
## Device Configuration
mangowm provides granular control over different input devices.
### Keyboard Settings
Control key repeat rates and layout rules.
| Setting | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `repeat_rate` | `int` | `25` | How many times a key repeats per second. |
| `repeat_delay` | `int` | `600` | Delay (ms) before a held key starts repeating. |
| `numlockon` | `0` or `1` | `0` | Enable NumLock on startup. |
| `xkb_rules_rules` | `string` | - | XKB rules file (e.g., `evdev`, `base`). Usually auto-detected. |
| `xkb_rules_model` | `string` | - | Keyboard model (e.g., `pc104`, `macbook`). |
| `xkb_rules_layout` | `string` | - | Keyboard layout code (e.g., `us`, `de`, `us,de`). |
| `xkb_rules_variant` | `string` | - | Layout variant (e.g., `dvorak`, `colemak`, `intl`). |
| `xkb_rules_options` | `string` | - | XKB options (e.g., `caps:escape`, `ctrl:nocaps`). |
**Example:**
```ini
repeat_rate=40
repeat_delay=300
numlockon=1
xkb_rules_layout=us,de
xkb_rules_variant=dvorak
xkb_rules_options=caps:escape,ctrl:nocaps
```
---
### Trackpad Settings
Specific settings for laptop touchpads. Some settings may require a relogin to take effect.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `disable_trackpad` | `0` | Set to `1` to disable the trackpad entirely. |
| `tap_to_click` | `1` | Tap to trigger a left click. |
| `tap_and_drag` | `1` | Tap and hold to drag items. |
| `trackpad_natural_scrolling` | `0` | Invert scrolling direction (natural scrolling). |
| `scroll_method` | `1` | `1` (Two-finger), `2` (Edge), `4` (Button). |
| `click_method` | `1` | `1` (Button areas), `2` (Clickfinger). |
| `drag_lock` | `1` | Lock dragging after tapping. |
| `disable_while_typing` | `1` | Disable trackpad while typing. |
| `left_handed` | `0` | Swap left/right buttons. |
| `middle_button_emulation` | `0` | Emulate middle button. |
| `swipe_min_threshold` | `1` | Minimum swipe threshold. |
---
**Detailed descriptions:**
- `scroll_method` values:
- `0` — Never send scroll events (no scrolling).
- `1` — Two-finger scrolling: send scroll events when two fingers are logically down on the device.
- `2` — Edge scrolling: send scroll events when a finger moves along the bottom or right edge.
- `4` — Button scrolling: send scroll events when a button is held and the device moves along a scroll axis.
- `click_method` values:
- `0` — No software click emulation.
- `1` — Button areas: use software-defined areas on the touchpad to generate button events.
- `2` — Clickfinger: the number of fingers determines which button is pressed.
- `accel_profile` values:
- `0` — No acceleration.
- `1` — Flat: no dynamic acceleration. Pointer speed = original input speed × (1 + `accel_speed`).
- `2` — Adaptive: slow movement results in less acceleration, fast movement results in more.
- `button_map` values:
- `0` — 1/2/3 finger tap maps to left / right / middle.
- `1` — 1/2/3 finger tap maps to left / middle / right.
- `send_events_mode` values:
- `0` — Send events from this device normally.
- `1` — Do not send events from this device.
- `2` — Disable this device when an external pointer device is plugged in.
---
### Mouse Settings
Configuration for external mice.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `mouse_natural_scrolling` | `0` | Invert scrolling direction. |
| `accel_profile` | `2` | `0` (None), `1` (Flat), `2` (Adaptive). |
| `accel_speed` | `0.0` | Speed adjustment (-1.0 to 1.0). |
| `left_handed` | `0` | Swap left and right buttons. |
| `middle_button_emulation` | `0` | Emulate middle button. |
| `swipe_min_threshold` | `1` | Minimum swipe threshold. |
| `send_events_mode` | `0` | `0` (Enabled), `1` (Disabled), `2` (Disabled on external mouse). |
| `button_map` | `0` | `0` (Left/right/middle), `1` (Left/middle/right). |
---
---
## Keyboard Layout Switching
To bind multiple layouts and toggle between them, define the layouts in `xkb_rules_layout` and use `xkb_rules_options` to set a toggle key combination. Then bind `switch_keyboard_layout` to trigger a switch.
```ini
# Define two layouts: US QWERTY and US Dvorak
xkb_rules_layout=us,us
xkb_rules_variant=,dvorak
xkb_rules_options=grp:lalt_lshift_toggle
```
Or bind it manually to a key:
```ini
# Bind Alt+Shift_L to cycle keyboard layout
bind=alt,shift_l,switch_keyboard_layout
```
Use `mmsg -g -k` to query the current keyboard layout at any time.
---
## Input Method Editor (IME)
To use Fcitx5 or IBus, set these environment variables in your config file.
> **Info:** These settings require a restart of the window manager to take effect.
**For Fcitx5:**
```ini
env=GTK_IM_MODULE,fcitx
env=QT_IM_MODULE,fcitx
env=SDL_IM_MODULE,fcitx
env=XMODIFIERS,@im=fcitx
env=GLFW_IM_MODULE,ibus
```
**For IBus:**
```ini
env=GTK_IM_MODULE,ibus
env=QT_IM_MODULE,ibus
env=XMODIFIERS,@im=ibus
```
docs/configuration/meta.json
+4
View File
@@ -0,0 +1,4 @@
{
"title": "Configuration",
"pages": ["basics", "monitors", "input", "xdg-portals", "miscellaneous"]
}
docs/configuration/miscellaneous.md
+51
View File
@@ -0,0 +1,51 @@
---
title: Miscellaneous
description: Advanced settings for XWayland, focus behavior, and system integration.
---
## System & Hardware
| Setting | Default | Description |
| :--- | :--- | :--- |
| `xwayland_persistence` | `1` | Keep XWayland running even when no X11 apps are open (reduces startup lag). |
| `syncobj_enable` | `0` | Enable `drm_syncobj` timeline support (helps with gaming stutter/lag). **Requires restart.** |
| `allow_lock_transparent` | `0` | Allow the lock screen to be transparent. |
| `allow_shortcuts_inhibit` | `1` | Allow shortcuts to be inhibited by clients. |
| `vrr` | - | Set via [monitor rule](/docs/configuration/monitors#monitor-rules). |
## Focus & Input
| Setting | Default | Description |
| :--- | :--- | :--- |
| `focus_on_activate` | `1` | Automatically focus windows when they request activation. |
| `sloppyfocus` | `1` | Focus follows the mouse cursor. |
| `warpcursor` | `1` | Warp the cursor to the center of the window when focus changes via keyboard. |
| `cursor_hide_timeout` | `0` | Hide the cursor after `N` seconds of inactivity (`0` to disable). |
| `drag_tile_to_tile` | `0` | Allow dragging a tiled window onto another to swap their positions. |
| `drag_corner` | `3` | Corner for drag-to-tile detection (0: none, 1–3: corners, 4: auto-detect). |
| `drag_warp_cursor` | `1` | Warp cursor when dragging windows to tile. |
| `axis_bind_apply_timeout` | `100` | Timeout (ms) for detecting consecutive scroll events for axis bindings. |
| `axis_scroll_factor` | `1.0` | Scroll factor for axis scroll speed (0.1–10.0). |
## Multi-Monitor & Tags
| Setting | Default | Description |
| :--- | :--- | :--- |
| `focus_cross_monitor` | `0` | Allow directional focus to cross monitor boundaries. |
| `exchange_cross_monitor` | `0` | Allow exchanging clients across monitor boundaries. |
| `focus_cross_tag` | `0` | Allow directional focus to cross into other tags. |
| `view_current_to_back` | `0` | Toggling the current tag switches back to the previously viewed tag. |
| `scratchpad_cross_monitor` | `0` | Share the scratchpad pool across all monitors. |
| `single_scratchpad` | `1` | Only allow one scratchpad (named or standard) to be visible at a time. |
| `circle_layout` | - | A comma-separated list of layouts `switch_layout` cycles through. |
## Window Behavior
| Setting | Default | Description |
| :--- | :--- | :--- |
| `enable_floating_snap` | `0` | Snap floating windows to edges or other windows. |
| `snap_distance` | `30` | Max distance (pixels) to trigger floating snap. |
| `no_border_when_single` | `0` | Remove window borders when only one window is visible on the tag. |
| `idleinhibit_ignore_visible` | `0` | Allow invisible clients (e.g., background audio players) to inhibit idle. |
| `drag_tile_refresh_interval` | `8.0` | Interval (1.0–16.0) to refresh tiled window resize during drag. Too small may cause application lag. |
| `drag_floating_refresh_interval` | `8.0` | Interval (1.0–16.0) to refresh floating window resize during drag. Too small may cause application lag. |
docs/configuration/monitors.md
+274
View File
@@ -0,0 +1,274 @@
---
title: Monitors
description: Manage display outputs, resolution, scaling, and tearing.
---
## Monitor Rules
You can configure each display output individually using the `monitorrule` keyword.
**Syntax:**
```ini
monitorrule=name:Values,Parameter:Values,Parameter:Values
```
> **Info:** If any of the matching fields (`name`, `make`, `model`, `serial`) are set, **all** of the set ones must match to be considered a match. Use `wlr-randr` to get your monitor's name, make, model, and serial.
### Parameters
| Parameter | Type | Values | Description |
| :--- | :--- | :--- | :--- |
| `name` | string | Any | Match by monitor name (supports regex) |
| `make` | string | Any | Match by monitor manufacturer |
| `model` | string | Any | Match by monitor model |
| `serial` | string | Any | Match by monitor serial number |
| `width` | integer | 0-9999 | Monitor width |
| `height` | integer | 0-9999 | Monitor height |
| `refresh` | float | 0.001-9999.0 | Monitor refresh rate |
| `x` | integer | 0-99999 | X position |
| `y` | integer | 0-99999 | Y position |
| `scale` | float | 0.01-100.0 | Monitor scale |
| `vrr` | integer | 0, 1 | Enable variable refresh rate |
| `rr` | integer | 0-7 | Monitor transform |
| `custom` | integer | 0, 1 | Enable custom mode (not supported on all displays — may cause black screen) |
### Transform Values
| Value | Rotation |
| :--- | :--- |
| `0` | No transform |
| `1` | 90° counter-clockwise |
| `2` | 180° counter-clockwise |
| `3` | 270° counter-clockwise |
| `4` | 180° vertical flip |
| `5` | Flip + 90° counter-clockwise |
| `6` | Flip + 180° counter-clockwise |
| `7` | Flip + 270° counter-clockwise |
> **Critical:** If you use XWayland applications, **never use negative coordinates** for your monitor positions. This is a known XWayland bug that causes click events to malfunction. Always arrange your monitors starting from `0,0` and extend into positive coordinates.
### Examples
```ini
# Laptop display: 1080p, 60Hz, positioned at origin
monitorrule=name:eDP-1,width:1920,height:1080,refresh:60,x:0,y:10
# Match by make and model instead of name
monitorrule=make:Chimei Innolux Corporation,model:0x15F5,width:1920,height:1080,refresh:60,x:0,y:0
# Virtual monitor with pattern matching
monitorrule=name:HEADLESS-.*,width:1920,height:1080,refresh:60,x:1926,y:0,scale:1,rr:0,vrr:0
```
---
## Monitor Spec Format
Several commands (`focusmon`, `tagmon`, `disable_monitor`, `enable_monitor`, `toggle_monitor`, `viewcrossmon`, `tagcrossmon`) accept a **monitor_spec** string to identify a monitor.
**Format:**
```text
name:xxx&&make:xxx&&model:xxx&&serial:xxx
```
- Any field can be omitted and there is no order requirement.
- If all fields are omitted, the string is treated as the monitor name directly (e.g., `eDP-1`).
- Use `wlr-randr` to find your monitor's name, make, model, and serial.
**Examples:**
```bash
# By name (shorthand)
mmsg -d toggle_monitor,eDP-1
# By make and model
mmsg -d toggle_monitor,make:Chimei Innolux Corporation&&model:0x15F5
# By serial
mmsg -d toggle_monitor,serial:12345678
```
---
## Tearing (Game Mode)
Tearing allows games to bypass the compositor's VSync for lower latency.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `allow_tearing` | `0` | Global tearing control: `0` (Disable), `1` (Enable), `2` (Fullscreen only). |
### Configuration
**Enable Globally:**
```ini
allow_tearing=1
```
**Enable per Window:**
Use a window rule to force tearing for specific games.
```ini
windowrule=force_tearing:1,title:vkcube
```
### Tearing Behavior Matrix
| `force_tearing` \ `allow_tearing` | DISABLED (0) | ENABLED (1) | FULLSCREEN_ONLY (2) |
| :--- | :--- | :--- | :--- |
| **UNSPECIFIED** (0) | Not Allowed | Follows tearing_hint | Only fullscreen follows tearing_hint |
| **ENABLED** (1) | Not Allowed | Allowed | Only fullscreen allowed |
| **DISABLED** (2) | Not Allowed | Not Allowed | Not Allowed |
### Graphics Card Compatibility
> **Warning:** Some graphics cards require setting the `WLR_DRM_NO_ATOMIC` environment variable before mango starts to successfully enable tearing.
Add this to `/etc/environment` and reboot:
```bash
WLR_DRM_NO_ATOMIC=1
```
Or run mango with the environment variable:
```bash
WLR_DRM_NO_ATOMIC=1 mango
```
---
## GPU Compatibility
If mango cannot display correctly or shows a black screen, try selecting a specific GPU:
```bash
# Use a single GPU
WLR_DRM_DEVICES=/dev/dri/card1 mango
# Use multiple GPUs
WLR_DRM_DEVICES=/dev/dri/card0:/dev/dri/card1 mango
```
Some GPUs have compatibility issues with `syncobj_enable=1` — it may crash apps like `kitty` that use syncobj. Set `WLR_DRM_NO_ATOMIC=1` in `/etc/environment` and reboot to resolve this.
---
## Power Management
You can control monitor power using the `mmsg` IPC tool.
```bash
# Turn off
mmsg -d disable_monitor,eDP-1
# Turn on
mmsg -d enable_monitor,eDP-1
# Toggle
mmsg -d toggle_monitor,eDP-1
```
You can also use `wlr-randr` for monitor management:
```bash
# Turn off monitor
wlr-randr --output eDP-1 --off
# Turn on monitor
wlr-randr --output eDP-1 --on
# Show all monitors
wlr-randr
```
---
## Screen Scale
### Without Global Scale (Recommended)
- If you do not use XWayland apps, you can use monitor rules or `wlr-randr` to set a global monitor scale.
- If you are using XWayland apps, it is not recommended to set a global monitor scale.
You can set scale like this, for example with a 1.4 factor.
**Dependencies:**
```bash
yay -S xorg-xrdb
yay -S xwayland-satellite
```
**In config file:**
```ini
env=QT_AUTO_SCREEN_SCALE_FACTOR,1
env=QT_WAYLAND_FORCE_DPI,140
```
**In autostart:**
```bash
echo "Xft.dpi: 140" | xrdb -merge
gsettings set org.gnome.desktop.interface text-scaling-factor 1.4
```
**Edit autostart for XWayland:**
```bash
# Start xwayland
/usr/sbin/xwayland-satellite :11 &
# Apply scale 1.4 for xwayland
sleep 0.5s && echo "Xft.dpi: 140" | xrdb -merge
```
### Using xwayland-satellite to Prevent Blurry XWayland Apps
If you use fractional scaling, you can use `xwayland-satellite` to automatically scale XWayland apps to prevent blurriness, for example with a scale of 1.4.
**Dependencies:**
```bash
yay -S xwayland-satellite
```
**In config file:**
```ini
env=DISPLAY,:2
exec=xwayland-satellite :2
monitorrule=name:eDP-1,width:1920,height:1080,refresh:60,x:0,y:0,scale:1.4,vrr:0,rr:0
```
> **Warning:** Use a `DISPLAY` value other than `:1` to avoid conflicting with mangowm.
---
## Virtual Monitors
You can create and manage virtual displays through IPC commands:
```bash
# Create virtual output
mmsg -d create_virtual_output
# Destroy all virtual outputs
mmsg -d destroy_all_virtual_output
```
You can configure virtual monitors using `wlr-randr`:
```bash
# Show all monitors
wlr-randr
# Configure virtual monitor
wlr-randr --output HEADLESS-1 --pos 1921,0 --scale 1 --custom-mode 1920x1080@60Hz
```
Virtual monitors can be used for screen sharing with tools like [Sunshine](https://github.com/LizardByte/Sunshine) and [Moonlight](https://github.com/moonlight-stream/moonlight-android), allowing other devices to act as extended monitors.
docs/configuration/xdg-portals.md
+76
View File
@@ -0,0 +1,76 @@
---
title: XDG Portals
description: Set up screen sharing, clipboard, keyring, and file pickers using XDG portals.
---
## Portal Configuration
You can customize portal settings via the following paths:
- **User Configuration (Priority):** `~/.config/xdg-desktop-portal/mango-portals.conf`
- **System Fallback:** `/usr/share/xdg-desktop-portal/mango-portals.conf`
> **Warning:** If you previously added `dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=wlroots` to your config, remove it. Mango now handles this automatically.
## Screen Sharing
To enable screen sharing (OBS, Discord, WebRTC), you need `xdg-desktop-portal-wlr`.
1. **Install Dependencies**
`pipewire`, `pipewire-pulse`, `xdg-desktop-portal-wlr`
2. **Optional: Add to autostart**
In some situations the portal may not start automatically. You can add this to your autostart script to ensure it launches:
```bash
/usr/lib/xdg-desktop-portal-wlr &
```
3. **Restart your computer** to apply changes.
### Known Issues
- **Window screen sharing:** Some applications may have issues sharing individual windows. See [#184](https://github.com/mangowm/mango/pull/184) for workarounds.
- **Screen recording lag:** If you experience stuttering during screen recording, see [xdg-desktop-portal-wlr#351](https://github.com/emersion/xdg-desktop-portal-wlr/issues/351).
## Clipboard Manager
Use `cliphist` to manage clipboard history.
**Dependencies:** `wl-clipboard`, `cliphist`, `wl-clip-persist`
**Autostart Config:**
```bash
# Keep clipboard content after app closes
wl-clip-persist --clipboard regular --reconnect-tries 0 &
# Watch clipboard and store history
wl-paste --type text --watch cliphist store &
```
## GNOME Keyring
If you need to store passwords or secrets (e.g., for VS Code or Minecraft launchers), install `gnome-keyring`.
**Configuration:**
Add the following to `~/.config/xdg-desktop-portal/mango-portals.conf`:
```ini
[preferred]
default=gtk
org.freedesktop.impl.portal.ScreenCast=wlr
org.freedesktop.impl.portal.Screenshot=wlr
org.freedesktop.impl.portal.Secret=gnome-keyring
org.freedesktop.impl.portal.Inhibit=none
```
## File Picker (File Selector)
**Dependencies:** `xdg-desktop-portal`, `xdg-desktop-portal-gtk`
Reboot your computer once to apply.
docs/faq.md
+101
View File
@@ -0,0 +1,101 @@
---
title: FAQ
description: Frequently asked questions and troubleshooting.
---
### How do I arrange tiled windows with my mouse?
You can enable the `drag_tile_to_tile` option in your config. This allows you to drag a tiled window onto another to swap them.
```ini
drag_tile_to_tile=1
```
---
### Why is my background blurry or why does blur look wrong?
Blur applies to the transparent areas of windows. To disable it entirely, set `blur=0`.
If you are experiencing **performance issues with blur**, make sure `blur_optimized=1` (the default). This caches the wallpaper as the blur background, which is much cheaper on the GPU:
```ini
blur_optimized=1
```
---
### Blur shows my wallpaper instead of the real background content
This is expected behavior when `blur_optimized=1` (the default). The optimizer caches the wallpaper to reduce GPU load — windows will blur against the wallpaper rather than the actual content stacked beneath them.
If you want blur to composite against the true background (i.e., show whatever is actually behind the window), set:
```ini
blur_optimized=0
```
> **Warning:** Disabling `blur_optimized` significantly increases GPU consumption and may cause rendering lag, especially on lower-end hardware.
---
### My games are lagging or stuttering
Try enabling **SyncObj** timeline support and **Adaptive Sync** (VRR) if your monitor supports it.
```ini
syncobj_enable=1
adaptive_sync=1
```
---
### My games have high input latency
You can enable **Tearing** (similar to VSync off).
First, enable it globally:
```ini
allow_tearing=1
```
Then force it for your specific game:
```ini
windowrule=force_tearing:1,title:Counter-Strike 2
```
> **Warning:** Some graphics cards require setting `WLR_DRM_NO_ATOMIC=1` before mango starts for tearing to work. Add it to `/etc/environment` and reboot, or launch mango with `WLR_DRM_NO_ATOMIC=1 mango`. See [Monitors — Tearing](/docs/configuration/monitors#tearing-game-mode) for details.
---
### How do I use pipes `|` in spawn commands?
The standard `spawn` command does not support shell pipes directly. You must use `spawn_shell` instead.
```ini
bind=SUPER,P,spawn_shell,echo "hello" | rofi -dmenu
```
---
### Certain key combinations do not work on my keyboard layout.
`bind` automatically converts keysym to keycode, which is compatible with most layouts but can sometimes be imprecise. If a key combination is not triggering, use the **keycode** directly instead of the key name.
Run `wev` and press the key to find its keycode, then use it in your bind:
```ini
# Instead of:
bind=ALT,q,killclient
# Use the keycode (e.g., code:24 = q on most layouts):
bind=ALT,code:24,killclient
```
You can also use `binds` (the `s` flag) to match by keysym instead of keycode:
```ini
binds=ALT,q,killclient
```
docs/index.md
+42
View File
@@ -0,0 +1,42 @@
---
title: Introduction
description: A lightweight and feature-rich Wayland compositor based on dwl.
---
**mango** is a Wayland compositor based on [dwl](https://codeberg.org/dwl/dwl/). It aims to be as lightweight as `dwl` and can be built completely within a few seconds, without compromising on functionality.
> **Philosophy:** **Lightweight & Fast**: mango is designed to be minimal yet functional. It compiles in seconds and offers a robust set of features out of the box.
## Feature Highlights
Beyond basic window management, mangowm provides a rich set of features designed for a modern Wayland experience.
- **[Animations](/docs/visuals/animations)** — Smooth, customizable animations for opening, moving, closing windows and tag switching.
- **[Layouts](/docs/window-management/layouts)** — Supports Scroller, Master-Stack, Monocle, Grid, Deck, and more, with per-tag layouts.
- **[Visual Effects](/docs/visuals/effects)** — Built-in blur, shadows, corner radius, and opacity effects powered by scenefx.
- **[IPC & Scripting](/docs/ipc)** — Control the compositor externally with robust IPC support for custom scripts and widgets.
## Additional Features
- **XWayland Support** — Excellent compatibility for legacy X11 applications.
- **Tag System** — Uses tags instead of workspaces, allowing separate window layouts for each tag.
- **Input Methods** — Great support for text input v2/v3 (Fcitx5, IBus).
- **Window States** — Rich states including swallow, minimize, maximize, fullscreen, and overlay.
- **Hot-Reload Config** — Simple external configuration that supports hot-reloading without restarting.
- **Scratchpads** — Support for both Sway-like and named scratchpads.
## Community
- **[Join the mangowm Discord](https://discord.gg/CPjbDxesh5)** — Chat with the community, get support, share your setup, and stay updated with the latest mangowm news.
- **[Join the GitHub Discussions](https://github.com/mangowm/mango/discussions)** — Ask questions, request features, report issues, or share ideas directly with contributors and other users.
## Acknowledgements
This project is built upon the hard work of several open-source projects:
- **[wlroots](https://gitlab.freedesktop.org/wlroots/wlroots)** — Implementation of the Wayland protocol.
- **[owl](https://github.com/dqrk0jeste/owl)** — Basal window animation reference.
- **[dwl](https://codeberg.org/dwl/dwl)** — Basal dwl features.
- **[sway](https://github.com/swaywm/sway)** — Sample implementation of the Wayland protocol.
- **[scenefx](https://github.com/wlrfx/scenefx)** — Library to simplify adding window effects.
docs/installation.md
+231
View File
@@ -0,0 +1,231 @@
---
title: Installation
description: Install mangowm on Arch, Fedora, Gentoo, Guix System, NixOS, PikaOS, or build from source.
---
## Package Installation
mangowm is available as a pre-built package on several distributions. Choose your distribution below.
---
### Arch Linux
mangowm is available in the **Arch User Repository (AUR)**.
You can install it using an AUR helper like `yay` or `paru`:
```bash
yay -S mangowm-git
```
> **Tip:** This package pulls the latest git version, ensuring you have the newest features and fixes.
---
### Fedora
The package is in the third-party **Terra repository**. First, add the Terra Repository.
> **Warning:** Both commands require root privileges. Use `sudo` if needed.
```bash
dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
```
Then, install the package:
```bash
dnf install mangowm
```
---
### Gentoo
The package is hosted in the community-maintained **GURU** repository.
1. **Add the GURU repository**
```bash
emerge --ask --verbose eselect-repository
eselect repository enable guru
emerge --sync guru
```
2. **Unmask packages**
Add the required packages to your `package.accept_keywords` file:
- `gui-libs/scenefx`
- `gui-wm/mangowm`
3. **Install mango**
```bash
emerge --ask --verbose gui-wm/mangowm
```
---
### Guix System
The package definition is described in the source repository.
1. **Add mango channel**
Add to `$HOME/.config/guix/channels.scm`:
```scheme
(cons (channel
(name 'mangowm)
(url "https://github.com/mangowm/mango.git")
(branch "main"))
%default-channels)
```
2. **Install**
After running `guix pull`, you can install mangowm:
```bash
guix install mangowm
```
Or add it to your system configuration using the mangowm module:
```scheme
(use-modules (mangowm))
(packages (cons*
mangowm-git
... ;; Other packages
%base-packages))
```
> **Tip:** For more information, see the [Guix System documentation](https://guix.gnu.org/manual/devel/en/html_node/Channels.html).
---
### NixOS
The repository provides a Flake with a NixOS module.
1. **Add flake input**
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
mangowm = {
url = "github:mangowm/mango";
inputs.nixpkgs.follows = "nixpkgs";
};
# other inputs ...
};
}
```
2. **Import the NixOS module**
**Option A — Import in `configuration.nix`:**
```nix
# configuration.nix (or any other file that you import)
{inputs, ...}: {
imports = [
inputs.mangowm.nixosModules.mango
# .. other imports ...
];
# ...
}
```
**Option B — Import directly in flake:**
```nix
# flake.nix
{
# ...
outputs = { self, nixpkgs, mangowm, ...}@inputs: let
inherit (nixpkgs) lib;
# ...
in {
nixosConfigurations.YourHostName = lib.nixosSystem {
modules = [
mangowm.nixosModules.mango # or inputs.mangowm.nixosModules.mango
# other imports ...
];
};
}
}
```
3. **Enable the module**
```nix
# configuration.nix (or any other file that you import)
{
programs.mango.enable = true;
}
```
4. **Extra options**
- `programs.mango.package` — the mango package to use, allows usage of custom mango drvs
- `programs.mango.addLoginEntry` (default: `true`) — adds login entry to the display manager
---
### PikaOS
mangowm is available in the **PikaOS package repository**.
You can install it using the `pikman` package manager:
```bash
pikman install mangowc
```
---
## Building from Source
If your distribution isn't listed above, or you want the latest unreleased changes, you can build mangowm from source.
> **Info:** Ensure the following dependencies are installed before proceeding:
> - `glibc`
> - `wayland`
> - `wayland-protocols`
> - `libinput`
> - `libdrm`
> - `libxkbcommon`
> - `pixman`
> - `git`
> - `meson`
> - `ninja`
> - `libdisplay-info`
> - `libliftoff`
> - `hwdata`
> - `seatd`
> - `pcre2`
> - `xorg-xwayland`
> - `libxcb`
You will need to build `wlroots` and `scenefx` manually as well.
1. **Build wlroots**
Clone and install the specific version required (check README for latest version).
```bash
git clone -b 0.19.2 https://gitlab.freedesktop.org/wlroots/wlroots.git
cd wlroots
meson build -Dprefix=/usr
sudo ninja -C build install
```
2. **Build scenefx**
This library handles the visual effects.
```bash
git clone -b 0.4.1 https://github.com/wlrfx/scenefx.git
cd scenefx
meson build -Dprefix=/usr
sudo ninja -C build install
```
3. **Build mangowm**
Finally, compile the compositor itself.
```bash
git clone https://github.com/mangowm/mango.git
cd mango
meson build -Dprefix=/usr
sudo ninja -C build install
```
docs/ipc.md
+154
View File
@@ -0,0 +1,154 @@
---
title: IPC
description: Control mangowm programmatically using mmsg.
---
## Introduction
mangowm includes a powerful IPC (Inter-Process Communication) tool called `mmsg`. This allows you to query the window manager's state, watch for events, and execute commands from external scripts.
## Basic Usage
The general syntax for `mmsg` is:
```bash
mmsg [-OTLq]
mmsg [-o <output>] -s [-t <tags>] [-l <layout>] [-c <tags>] [-d <cmd>,<arg1>,<arg2>,<arg3>,<arg4>,<arg5>]
mmsg [-o <output>] (-g | -w) [-OotlcvmfxekbA]
```
### Options
| Flag | Description |
| :--- | :--- |
| `-q` | Quit mangowm. |
| `-g` | **Get** values (tags, layout, focused client). |
| `-s` | **Set** values (switch tags, layouts). |
| `-w` | **Watch** mode (streams events). |
| `-O` | Get all output (monitor) information. |
| `-T` | Get number of tags. |
| `-L` | Get all available layouts. |
| `-o` | Select output (monitor). |
| `-t` | Get/set selected tags (set with `[+-^.]`). |
| `-l` | Get/set current layout. |
| `-c` | Get title and appid of focused client. |
| `-v` | Get visibility of statusbar. |
| `-m` | Get fullscreen status. |
| `-f` | Get floating status. |
| `-d` | **Dispatch** an internal command. |
| `-x` | Get focused client geometry. |
| `-e` | Get the name of the last focused layer. |
| `-k` | Get current keyboard layout. |
| `-b` | Get current keybind mode. |
| `-A` | Get scale factor of monitor. |
## Examples
### Tag Management
You can perform arithmetic on tags using the `-t` flag with `-s` (set).
```bash
# Switch to Tag 1
mmsg -t 1
# Add Tag 2 to current view (Multiview)
mmsg -s -t 2+
# Remove Tag 2 from current view
mmsg -s -t 2-
# Toggle Tag 2
mmsg -s -t 2^
```
### Layouts
Switch layouts programmatically. Layout codes: `S` (Scroller), `T` (Tile), `G` (Grid), `M` (Monocle), `K` (Deck), `CT` (Center Tile), `RT` (Right Tile), `VS` (Vertical Scroller), `VT` (Vertical Tile), `VG` (Vertical Grid), `VK` (Vertical Deck), `TG` (TGMix).
```bash
# Switch to Scroller
mmsg -l "S"
# Switch to Tile
mmsg -l "T"
```
### Dispatching Commands
Any command available in `config.conf` keybindings can be run via IPC.
```bash
# Close the focused window
mmsg -d killclient
# Resize window by +10 width
mmsg -d resizewin,+10,0
# Toggle fullscreen
mmsg -d togglefullscreen
# Disable a monitor power
mmsg -d disable_monitor,eDP-1
```
### Monitoring & Status
Use `-g` or `-w` to build custom status bars or automation scripts.
```bash
# Watch for all message changes
mmsg -w
# Get all messages without watch
mmsg -g
# Watch focused client appid and title
mmsg -w -c
# Get all available outputs
mmsg -O
# Get all tags message
mmsg -g -t
# Get current focused client message
mmsg -g -c
# Get current keyboard layout
mmsg -g -k
# Get current keybind mode
mmsg -g -b
# Get scale factor of current monitor
mmsg -g -A
```
#### Tag Message Format
- State: 0 → none, 1 → active, 2 → urgent
Example output:
| Monitor | Tag Number | Tag State | Clients in Tag | Focused Client |
|---------|------------|-----------|----------------|----------------|
| eDP-1 | tag 2 | 0 | 1 | 0 |
| Monitor | occupied tags mask | active tags mask | urgent tags mask |
|---------|--------------------|------------------|------------------|
| eDP-1 | 14 | 6 | 0 |
## Virtual Monitors
You can create headless outputs for screen mirroring or remote desktop access (e.g., Sunshine/Moonlight).
```bash
# Create a virtual output
mmsg -d create_virtual_output
# Configure it (set resolution)
wlr-randr --output HEADLESS-1 --pos 1920,0 --mode 1920x1080@60Hz
# Destroy all virtual outputs
mmsg -d destroy_all_virtual_output
docs/meta.json
+14
View File
@@ -0,0 +1,14 @@
{
"title": "mangowm",
"pages": [
"index",
"installation",
"quick-start",
"configuration",
"visuals",
"window-management",
"bindings",
"ipc",
"faq"
]
}
docs/quick-start.md
+88
View File
@@ -0,0 +1,88 @@
---
title: Quick Start
description: Basic configuration and first steps with mangowm.
---
Now that you have mangowm installed, let's get your environment set up.
## Initial Setup
1. **Create Configuration Directory**
mangowm looks for configuration files in `~/.config/mango/`.
```bash
mkdir -p ~/.config/mango
```
2. **Copy Default Config**
A default configuration file is provided at `/etc/mango/config.conf`. Copy it to your local directory to start customizing.
```bash
cp /etc/mango/config.conf ~/.config/mango/config.conf
```
3. **Launch mangowm**
You can now start the compositor from your TTY.
```bash
mango
```
Optional: To specify a custom config file path:
```bash
mango -c /path/to/your/config.conf
```
## Essential Keybindings
mangowm uses the following keybinds by default:
| Key Combination | Action |
| :--- | :--- |
| `Alt` + `Return` | Open Terminal (defaults to `foot`) |
| `Alt` + `Space` | Open Launcher (defaults to `rofi`) |
| `Alt` + `Q` | Close (Kill) the active window |
| `Super` + `M` | Quit mangowm |
| `Super` + `F` | Toggle Fullscreen |
| `Alt` + `Arrow Keys` | Move focus (Left, Right, Up, Down) |
| `Ctrl` + `1-9` | Switch to Tag 1-9 |
| `Alt` + `1-9` | Move window to Tag 1-9 |
> **Warning:** Some default bindings rely on specific tools like `foot` (terminal) and `rofi` (launcher). Ensure you have them installed or update your `config.conf` to use your preferred alternatives.
## Recommended Tools
To get a fully functional desktop experience, we recommend installing the following components:
| Category | Recommended Tools |
| :--- | :--- |
| Application Launcher | rofi, bemenu, wmenu, fuzzel |
| Terminal Emulator | foot, wezterm, alacritty, kitty, ghostty |
| Status Bar | waybar, eww, quickshell, ags |
| Desktop Shell | Noctalia, DankMaterialShell |
| Wallpaper Setup | swww, swaybg |
| Notification Daemon | swaync, dunst, mako |
| Desktop Portal | xdg-desktop-portal, xdg-desktop-portal-wlr, xdg-desktop-portal-gtk |
| Clipboard | wl-clipboard, wl-clip-persist, cliphist |
| Gamma Control / Night Light | wlsunset, gammastep |
| Miscellaneous | xfce-polkit, wlogout |
## Example Configuration
Check out the [example configuration](https://github.com/DreamMaoMao/mango-config) by the creator of mangowm, including complete setups for mangowm, Waybar, Rofi, and more.
```bash
git clone https://github.com/DreamMaoMao/mango-config.git ~/.config/mango
```
## Next Steps
Now that you are up and running, dive deeper into customizing mangowm:
- [Configure Monitors](/docs/configuration/monitors) — Set up resolution, scaling, and multi-monitor layouts.
- [Window Rules](/docs/window-management/rules#window-rules) — Define how specific applications should behave.
- [Appearance](/docs/visuals/theming) — Customize colors, borders, gaps, and effects.
docs/visuals/animations.md
+108
View File
@@ -0,0 +1,108 @@
---
title: Animations
description: Configure smooth transitions for windows and layers.
---
## Enabling Animations
mangowm supports animations for both standard windows and layer shell surfaces (like bars and notifications).
```ini
animations=1
layer_animations=1
```
## Animation Types
You can define different animation styles for opening and closing windows and layer surfaces.
Available types: `slide`, `zoom`, `fade`, `none`.
```ini
animation_type_open=zoom
animation_type_close=slide
layer_animation_type_open=slide
layer_animation_type_close=slide
```
## Fade Settings
Control the fade-in and fade-out effects for animations.
```ini
animation_fade_in=1
animation_fade_out=1
fadein_begin_opacity=0.5
fadeout_begin_opacity=0.5
```
- `animation_fade_in` — Enable fade-in effect (0: disable, 1: enable)
- `animation_fade_out` — Enable fade-out effect (0: disable, 1: enable)
- `fadein_begin_opacity` — Starting opacity for fade-in animations (0.0–1.0)
- `fadeout_begin_opacity` — Starting opacity for fade-out animations (0.0–1.0)
## Zoom Settings
Adjust the zoom ratios for zoom animations.
```ini
zoom_initial_ratio=0.3
zoom_end_ratio=0.8
```
- `zoom_initial_ratio` — Initial zoom ratio
- `zoom_end_ratio` — End zoom ratio
## Durations
Control the speed of animations (in milliseconds).
| Setting | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `animation_duration_move` | integer | `500` | Move animation duration (ms) |
| `animation_duration_open` | integer | `400` | Open animation duration (ms) |
| `animation_duration_tag` | integer | `300` | Tag animation duration (ms) |
| `animation_duration_close` | integer | `300` | Close animation duration (ms) |
| `animation_duration_focus` | integer | `0` | Focus change (opacity transition) animation duration (ms) |
```ini
animation_duration_move=500
animation_duration_open=400
animation_duration_tag=300
animation_duration_close=300
animation_duration_focus=0
```
## Custom Bezier Curves
Bezier curves determine the "feel" of an animation (e.g., linear vs. bouncy). The format is `x1,y1,x2,y2`.
You can visualize and generate curve values using online tools like [cssportal.com](https://www.cssportal.com/css-cubic-bezier-generator/) or [easings.net](https://easings.net).
| Setting | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `animation_curve_open` | string | `0.46,1.0,0.29,0.99` | Open animation bezier curve |
| `animation_curve_move` | string | `0.46,1.0,0.29,0.99` | Move animation bezier curve |
| `animation_curve_tag` | string | `0.46,1.0,0.29,0.99` | Tag animation bezier curve |
| `animation_curve_close` | string | `0.46,1.0,0.29,0.99` | Close animation bezier curve |
| `animation_curve_focus` | string | `0.46,1.0,0.29,0.99` | Focus change (opacity transition) animation bezier curve |
| `animation_curve_opafadein` | string | `0.46,1.0,0.29,0.99` | Open opacity animation bezier curve |
| `animation_curve_opafadeout` | string | `0.5,0.5,0.5,0.5` | Close opacity animation bezier curve |
```ini
animation_curve_open=0.46,1.0,0.29,0.99
animation_curve_move=0.46,1.0,0.29,0.99
animation_curve_tag=0.46,1.0,0.29,0.99
animation_curve_close=0.46,1.0,0.29,0.99
animation_curve_focus=0.46,1.0,0.29,0.99
animation_curve_opafadein=0.46,1.0,0.29,0.99
animation_curve_opafadeout=0.5,0.5,0.5,0.5
```
## Tag Animation Direction
Control the direction of tag switch animations.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `tag_animation_direction` | `1` | Tag animation direction (1: horizontal, 0: vertical) |
docs/visuals/effects.md
+82
View File
@@ -0,0 +1,82 @@
---
title: Window Effects
description: Add visual polish with blur, shadows, and opacity.
---
## Blur
Blur creates a frosted glass effect for transparent windows.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `blur` | `0` | Enable blur for windows. |
| `blur_layer` | `0` | Enable blur for layer surfaces (like bars/docks). |
| `blur_optimized` | `1` | Caches the wallpaper and blur background, significantly reducing GPU usage. Disabling it will significantly increase GPU consumption and may cause rendering lag. **Highly recommended.** |
| `blur_params_radius` | `5` | The strength (radius) of the blur. |
| `blur_params_num_passes` | `1` | Number of passes. Higher = smoother but more expensive. |
| `blur_params_noise` | `0.02` | Blur noise level. |
| `blur_params_brightness` | `0.9` | Blur brightness adjustment. |
| `blur_params_contrast` | `0.9` | Blur contrast adjustment. |
| `blur_params_saturation` | `1.2` | Blur saturation adjustment. |
> **Warning:** Blur has a relatively high impact on performance. If your hardware is limited, it is not recommended to enable it. If you experience lag with blur on, ensure `blur_optimized=1` — disabling it will significantly increase GPU consumption and may cause rendering lag. To disable blur entirely, set `blur=0`.
---
## Shadows
Drop shadows help distinguish floating windows from the background.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `shadows` | `0` | Enable shadows. |
| `layer_shadows` | `0` | Enable shadows for layer surfaces. |
| `shadow_only_floating` | `1` | Only draw shadows for floating windows (saves performance). |
| `shadows_size` | `10` | Size of the shadow. |
| `shadows_blur` | `15` | Shadow blur amount. |
| `shadows_position_x` | `0` | Shadow X offset. |
| `shadows_position_y` | `0` | Shadow Y offset. |
| `shadowscolor` | `0x000000ff` | Color of the shadow. |
```ini
# Example shadows configuration
shadows=1
layer_shadows=1
shadow_only_floating=1
shadows_size=12
shadows_blur=15
shadows_position_x=0
shadows_position_y=0
shadowscolor=0x000000ff
```
---
## Opacity & Corner Radius
Control the transparency and roundness of your windows.
| Setting | Default | Description |
| :--- | :--- | :--- |
| `border_radius` | `0` | Window corner radius in pixels. |
| `border_radius_location_default` | `0` | Corner radius location: `0` (all), `1` (top-left), `2` (top-right), `3` (bottom-left), `4` (bottom-right), `5` (closest corner). |
| `no_radius_when_single` | `0` | Disable radius if only one window is visible. |
| `focused_opacity` | `1.0` | Opacity for the active window (0.0 - 1.0). |
| `unfocused_opacity` | `1.0` | Opacity for inactive windows (0.0 - 1.0). |
```ini
# Window corner radius in pixels
border_radius=0
# Corner radius location (0=all, 1=top-left, 2=top-right, 3=bottom-left, 4=bottom-right)
border_radius_location_default=0
# Disable radius if only one window is visible
no_radius_when_single=0
# Opacity for the active window (0.0 - 1.0)
focused_opacity=1.0
# Opacity for inactive windows
unfocused_opacity=1.0
```

Some files were not shown because too many files have changed in this diff Show More