mirror of
https://github.com/DreamMaoMao/maomaowm.git
synced 2026-03-14 05:34:21 -04:00
feat: add docs and sync with wiki & website
This commit is contained in:
atheeq-rhxn
parent
1fc89d01eb
commit
5906d9621e
28 changed files with 2594 additions and 0 deletions
61
.github/scripts/sync-wiki.py
vendored
Normal file
61
.github/scripts/sync-wiki.py
vendored
Normal 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()
|
||||
42
.github/workflows/sync-website.yml
vendored
Normal file
42
.github/workflows/sync-website.yml
vendored
Normal 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
|
||||
40
.github/workflows/sync-wiki.yml
vendored
Normal file
40
.github/workflows/sync-wiki.yml
vendored
Normal 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
|
||||
204
docs/bindings/keys.md
Normal file
204
docs/bindings/keys.md
Normal 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. |
|
||||
4
docs/bindings/meta.json
Normal file
4
docs/bindings/meta.json
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"title": "Bindings & Input",
|
||||
"pages": ["keys", "mouse-gestures"]
|
||||
}
|
||||
116
docs/bindings/mouse-gestures.md
Normal file
116
docs/bindings/mouse-gestures.md
Normal 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
|
||||
```
|
||||
87
docs/configuration/basics.md
Normal file
87
docs/configuration/basics.md
Normal 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
|
||||
```
|
||||
150
docs/configuration/input.md
Normal file
150
docs/configuration/input.md
Normal 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
|
||||
```
|
||||
4
docs/configuration/meta.json
Normal file
4
docs/configuration/meta.json
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"title": "Configuration",
|
||||
"pages": ["basics", "monitors", "input", "xdg-portals", "miscellaneous"]
|
||||
}
|
||||
51
docs/configuration/miscellaneous.md
Normal file
51
docs/configuration/miscellaneous.md
Normal 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. |
|
||||
274
docs/configuration/monitors.md
Normal file
274
docs/configuration/monitors.md
Normal 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.
|
||||
76
docs/configuration/xdg-portals.md
Normal file
76
docs/configuration/xdg-portals.md
Normal 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.
|
||||
101
docs/faq.md
Normal file
101
docs/faq.md
Normal 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
|
||||
```
|
||||
42
docs/index.md
Normal file
42
docs/index.md
Normal 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.
|
||||
231
docs/installation.md
Normal file
231
docs/installation.md
Normal 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
|
||||
```
|
||||
154
docs/ipc.md
Normal file
154
docs/ipc.md
Normal 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
|
||||
14
docs/meta.json
Normal file
14
docs/meta.json
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
{
|
||||
"title": "mangowm",
|
||||
"pages": [
|
||||
"index",
|
||||
"installation",
|
||||
"quick-start",
|
||||
"configuration",
|
||||
"visuals",
|
||||
"window-management",
|
||||
"bindings",
|
||||
"ipc",
|
||||
"faq"
|
||||
]
|
||||
}
|
||||
88
docs/quick-start.md
Normal file
88
docs/quick-start.md
Normal 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.
|
||||
108
docs/visuals/animations.md
Normal file
108
docs/visuals/animations.md
Normal 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) |
|
||||
82
docs/visuals/effects.md
Normal file
82
docs/visuals/effects.md
Normal 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
|
||||
```
|
||||
4
docs/visuals/meta.json
Normal file
4
docs/visuals/meta.json
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"title": "Visuals",
|
||||
"pages": ["theming", "status-bar", "effects", "animations"]
|
||||
}
|
||||
141
docs/visuals/status-bar.md
Normal file
141
docs/visuals/status-bar.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
---
|
||||
title: Status Bar
|
||||
description: Configure Waybar for mangowm.
|
||||
---
|
||||
|
||||
## Module Configuration
|
||||
|
||||
mangowm is compatible with Waybar's `ext/workspaces` module (Wayland standard) or the `dwl/tags` module. We recommend `ext/workspaces` for the best experience.
|
||||
|
||||
> **Tip:** You can also use the `dwl/tags` module, but `ext/workspaces` provides better integration with mangowm's features. The `ext/workspaces` module requires **Waybar > 0.14.0**.
|
||||
|
||||
### `config.jsonc`
|
||||
|
||||
Add the following to your Waybar configuration:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"modules-left": [
|
||||
"ext/workspaces",
|
||||
"dwl/window"
|
||||
],
|
||||
"ext/workspaces": {
|
||||
"format": "{icon}",
|
||||
"ignore-hidden": true,
|
||||
"on-click": "activate",
|
||||
"on-click-right": "deactivate",
|
||||
"sort-by-id": true
|
||||
},
|
||||
"dwl/window": {
|
||||
"format": "[{layout}] {title}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Styling
|
||||
|
||||
You can style the tags using standard CSS in `style.css`.
|
||||
|
||||
### `style.css`
|
||||
|
||||
```css
|
||||
#workspaces {
|
||||
border-radius: 4px;
|
||||
border-width: 2px;
|
||||
border-style: solid;
|
||||
border-color: #c9b890;
|
||||
margin-left: 4px;
|
||||
padding-left: 10px;
|
||||
padding-right: 6px;
|
||||
background: rgba(40, 40, 40, 0.76);
|
||||
}
|
||||
|
||||
#workspaces button {
|
||||
border: none;
|
||||
background: none;
|
||||
box-shadow: inherit;
|
||||
text-shadow: inherit;
|
||||
color: #ddca9e;
|
||||
padding: 1px;
|
||||
padding-left: 1px;
|
||||
padding-right: 1px;
|
||||
margin-right: 2px;
|
||||
margin-left: 2px;
|
||||
}
|
||||
|
||||
#workspaces button.hidden {
|
||||
color: #9e906f;
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
#workspaces button.visible {
|
||||
color: #ddca9e;
|
||||
}
|
||||
|
||||
#workspaces button:hover {
|
||||
color: #d79921;
|
||||
}
|
||||
|
||||
#workspaces button.active {
|
||||
background-color: #ddca9e;
|
||||
color: #282828;
|
||||
margin-top: 5px;
|
||||
margin-bottom: 5px;
|
||||
padding-top: 1px;
|
||||
padding-bottom: 0px;
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
#workspaces button.urgent {
|
||||
background-color: #ef5e5e;
|
||||
color: #282828;
|
||||
margin-top: 5px;
|
||||
margin-bottom: 5px;
|
||||
padding-top: 1px;
|
||||
padding-bottom: 0px;
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
#tags {
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
#tags button {
|
||||
background-color: #fff;
|
||||
color: #a585cd;
|
||||
}
|
||||
|
||||
#tags button:not(.occupied):not(.focused) {
|
||||
font-size: 0;
|
||||
min-width: 0;
|
||||
min-height: 0;
|
||||
margin: -17px;
|
||||
padding: 0;
|
||||
color: transparent;
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
#tags button.occupied {
|
||||
background-color: #fff;
|
||||
color: #cdc885;
|
||||
}
|
||||
|
||||
#tags button.focused {
|
||||
background-color: rgb(186, 142, 213);
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
#tags button.urgent {
|
||||
background: rgb(171, 101, 101);
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
#window {
|
||||
background-color: rgb(237, 196, 147);
|
||||
color: rgb(63, 37, 5);
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Configuration Example
|
||||
|
||||
> **Tip:** You can find a complete Waybar configuration for mangowm at [waybar-config](https://github.com/DreamMaoMao/waybar-config).
|
||||
59
docs/visuals/theming.md
Normal file
59
docs/visuals/theming.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
title: Theming
|
||||
description: Customize the visual appearance of borders, colors, and the cursor.
|
||||
---
|
||||
|
||||
## Dimensions
|
||||
|
||||
Control the sizing of window borders and gaps.
|
||||
|
||||
| Setting | Default | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `borderpx` | `4` | Border width in pixels. |
|
||||
| `gappih` | `5` | Horizontal inner gap (between windows). |
|
||||
| `gappiv` | `5` | Vertical inner gap. |
|
||||
| `gappoh` | `10` | Horizontal outer gap (between windows and screen edges). |
|
||||
| `gappov` | `10` | Vertical outer gap. |
|
||||
|
||||
## Colors
|
||||
|
||||
Colors are defined in `0xRRGGBBAA` hex format.
|
||||
|
||||
```ini
|
||||
# Background color of the root window
|
||||
rootcolor=0x323232ff
|
||||
|
||||
# Inactive window border
|
||||
bordercolor=0x444444ff
|
||||
|
||||
# Active window border
|
||||
focuscolor=0xc66b25ff
|
||||
|
||||
# Urgent window border (alerts)
|
||||
urgentcolor=0xad401fff
|
||||
```
|
||||
|
||||
### State-Specific Colors
|
||||
|
||||
You can also color-code windows based on their state:
|
||||
|
||||
| State | Config Key | Default Color |
|
||||
| :--- | :--- | :--- |
|
||||
| Maximized | `maximizescreencolor` | `0x89aa61ff` |
|
||||
| Scratchpad | `scratchpadcolor` | `0x516c93ff` |
|
||||
| Global | `globalcolor` | `0xb153a7ff` |
|
||||
| Overlay | `overlaycolor` | `0x14a57cff` |
|
||||
|
||||
> **Tip:** For scratchpad window sizing, see [Scratchpad](/docs/window-management/scratchpad) configuration.
|
||||
|
||||
## Cursor Theme
|
||||
|
||||
Set the size and theme of your mouse cursor.
|
||||
|
||||
```ini
|
||||
cursor_size=24
|
||||
cursor_theme=Adwaita
|
||||
```
|
||||
|
||||
> **Tip:** You may also want to set the `XCURSOR_SIZE` environment variable to match:
|
||||
> `env=XCURSOR_SIZE,24`
|
||||
99
docs/window-management/layouts.md
Normal file
99
docs/window-management/layouts.md
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
---
|
||||
title: Layouts
|
||||
description: Configure and switch between different window layouts.
|
||||
---
|
||||
|
||||
## Supported Layouts
|
||||
|
||||
mangowm supports a variety of layouts that can be assigned per tag.
|
||||
|
||||
- `tile`
|
||||
- `scroller`
|
||||
- `monocle`
|
||||
- `grid`
|
||||
- `deck`
|
||||
- `center_tile`
|
||||
- `vertical_tile`
|
||||
- `right_tile`
|
||||
- `vertical_scroller`
|
||||
- `vertical_grid`
|
||||
- `vertical_deck`
|
||||
- `tgmix`
|
||||
|
||||
---
|
||||
|
||||
## Scroller Layout
|
||||
|
||||
The Scroller layout positions windows in a scrollable strip, similar to PaperWM.
|
||||
|
||||
### Configuration
|
||||
|
||||
| Setting | Default | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `scroller_structs` | `20` | Width reserved on sides when window ratio is 1. |
|
||||
| `scroller_default_proportion` | `0.9` | Default width proportion for new windows. |
|
||||
| `scroller_focus_center` | `0` | Always center the focused window (1 = enable). |
|
||||
| `scroller_prefer_center` | `0` | Center focused window only if it was outside the view. |
|
||||
| `scroller_prefer_overspread` | `1` | Allow windows to overspread when there's extra space. |
|
||||
| `edge_scroller_pointer_focus` | `1` | Focus windows even if partially off-screen. |
|
||||
| `scroller_proportion_preset` | `0.5,0.8,1.0` | Presets for cycling window widths. |
|
||||
| `scroller_ignore_proportion_single` | `1` | Ignore proportion adjustments for single windows. |
|
||||
| `scroller_default_proportion_single` | `1.0` | Default proportion for single windows in scroller. **Requires `scroller_ignore_proportion_single=0` to take effect.** |
|
||||
|
||||
> **Warning:** `scroller_prefer_overspread`, `scroller_focus_center`, and `scroller_prefer_center` interact with each other. Their priority order is:
|
||||
>
|
||||
> **scroller_prefer_overspread > scroller_focus_center > scroller_prefer_center**
|
||||
>
|
||||
> To ensure a lower-priority setting takes effect, you must set all higher-priority options to `0`.
|
||||
|
||||
```ini
|
||||
# Example scroller configuration
|
||||
scroller_structs=20
|
||||
scroller_default_proportion=0.9
|
||||
scroller_focus_center=0
|
||||
scroller_prefer_center=0
|
||||
scroller_prefer_overspread=1
|
||||
edge_scroller_pointer_focus=1
|
||||
scroller_default_proportion_single=1.0
|
||||
scroller_proportion_preset=0.5,0.8,1.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Master-Stack Layouts
|
||||
|
||||
These settings apply to layouts like `tile` and `center_tile`.
|
||||
|
||||
| Setting | Default | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `new_is_master` | `1` | New windows become the master window. |
|
||||
| `default_mfact` | `0.55` | The split ratio between master and stack areas. |
|
||||
| `default_nmaster` | `1` | Number of allowed master windows. |
|
||||
| `smartgaps` | `0` | Disable gaps when only one window is present. |
|
||||
| `center_master_overspread` | `0` | (Center Tile) Master spreads across screen if no stack exists. |
|
||||
| `center_when_single_stack` | `1` | (Center Tile) Center master when only one stack window exists. |
|
||||
|
||||
```ini
|
||||
# Example master-stack configuration
|
||||
new_is_master=1
|
||||
smartgaps=0
|
||||
default_mfact=0.55
|
||||
default_nmaster=1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Switching Layouts
|
||||
|
||||
You can switch layouts dynamically or set a default for specific tags using [Tag Rules](/docs/window-management/rules#tag-rules).
|
||||
|
||||
**Keybinding Examples:**
|
||||
|
||||
```ini
|
||||
# Cycle through layouts
|
||||
bind=SUPER,n,switch_layout
|
||||
|
||||
# Set specific layout
|
||||
bind=SUPER,t,setlayout,tile
|
||||
bind=SUPER,s,setlayout,scroller
|
||||
```
|
||||
4
docs/window-management/meta.json
Normal file
4
docs/window-management/meta.json
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"title": "Window Management",
|
||||
"pages": ["layouts", "rules", "overview", "scratchpad"]
|
||||
}
|
||||
36
docs/window-management/overview.md
Normal file
36
docs/window-management/overview.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
title: Overview
|
||||
description: Configure the overview mode for window navigation.
|
||||
---
|
||||
|
||||
## Overview Settings
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `hotarea_size` | integer | `10` | Hot area size in pixels. |
|
||||
| `enable_hotarea` | integer | `1` | Enable hot areas (0: disable, 1: enable). |
|
||||
| `hotarea_corner` | integer | `2` | Hot area corner (0: top-left, 1: top-right, 2: bottom-left, 3: bottom-right). |
|
||||
| `ov_tab_mode` | integer | `0` | Overview tab mode (0: disable, 1: enable). |
|
||||
| `overviewgappi` | integer | `5` | Inner gap in overview mode. |
|
||||
| `overviewgappo` | integer | `30` | Outer gap in overview mode. |
|
||||
|
||||
### Setting Descriptions
|
||||
|
||||
- `enable_hotarea` — Toggles overview when the cursor enters the configured corner.
|
||||
- `hotarea_size` — Size of the hot area trigger zone in pixels.
|
||||
- `hotarea_corner` — Corner that triggers the hot area (0: top-left, 1: top-right, 2: bottom-left, 3: bottom-right).
|
||||
- `ov_tab_mode` — Circles focus through windows in overview; releasing the mod key exits overview.
|
||||
|
||||
### Mouse Interaction in Overview
|
||||
|
||||
When in overview mode:
|
||||
|
||||
- **Left mouse button** — Jump to (focus) a window.
|
||||
- **Right mouse button** — Close a window.
|
||||
|
||||
To enable this behavior, add the following mouse bindings to your config:
|
||||
|
||||
```ini
|
||||
mousebind=NONE,btn_left,toggleoverview,1
|
||||
mousebind=NONE,btn_right,killclient,0
|
||||
```
|
||||
249
docs/window-management/rules.md
Normal file
249
docs/window-management/rules.md
Normal file
|
|
@ -0,0 +1,249 @@
|
|||
---
|
||||
title: Rules
|
||||
description: Define behavior for specific windows, tags, and layers.
|
||||
---
|
||||
|
||||
## Window Rules
|
||||
|
||||
Window rules allow you to set specific properties (floating, opacity, size, animations, etc.) for applications based on their `appid` or `title`. You can set all parameters in one line, and if you both set appid and title, the window will only follow the rules when appid and title both match.
|
||||
|
||||
**Format:**
|
||||
|
||||
```ini
|
||||
windowrule=Parameter:Values,title:Values
|
||||
windowrule=Parameter:Values,Parameter:Values,appid:Values,title:Values
|
||||
```
|
||||
|
||||
### State & Behavior Parameters
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `appid` | string | Any | Match by application ID, supports regex |
|
||||
| `title` | string | Any | Match by window title, supports regex |
|
||||
| `isfloating` | integer | `0` / `1` | Force floating state |
|
||||
| `isfullscreen` | integer | `0` / `1` | Force fullscreen state |
|
||||
| `isfakefullscreen` | integer | `0` / `1` | Force fake-fullscreen state (window stays constrained) |
|
||||
| `isglobal` | integer | `0` / `1` | Open as global window (sticky across tags) |
|
||||
| `isoverlay` | integer | `0` / `1` | Make it always in top layer |
|
||||
| `isopensilent` | integer | `0` / `1` | Open without focus |
|
||||
| `istagsilent` | integer | `0` / `1` | Don't focus if client is not in current view tag |
|
||||
| `force_maximize` | integer | `0` / `1` (default 1) | The state of client default to maximized |
|
||||
| `ignore_maximize` | integer | `0` / `1` (default 1) | Don't handle maximize request from client |
|
||||
| `ignore_minimize` | integer | `0` / `1` (default 1) | Don't handle minimize request from client |
|
||||
| `force_tiled_state` | integer | `0` / `1` | Deceive the window into thinking it is tiling, so it better adheres to assigned dimensions |
|
||||
| `noopenmaximized` | integer | `0` / `1` | Window does not open as maximized mode |
|
||||
| `single_scratchpad` | integer | `0` / `1` (default 1) | Only show one out of named scratchpads or the normal scratchpad |
|
||||
| `allow_shortcuts_inhibit` | integer | `0` / `1` (default 1) | Allow shortcuts to be inhibited by clients |
|
||||
| `indleinhibit_when_focus` | integer | `0` / `1` (default 0) | Automatically keep idle inhibit active when this window is focused |
|
||||
|
||||
### Geometry & Position
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `width` | integer | 0-9999 | Window width when it becomes a floating window |
|
||||
| `height` | integer | 0-9999 | Window height when it becomes a floating window |
|
||||
| `offsetx` | integer | -999-999 | X offset from center (%), 100 is the edge of screen with outer gap |
|
||||
| `offsety` | integer | -999-999 | Y offset from center (%), 100 is the edge of screen with outer gap |
|
||||
| `monitor` | string | Any | Assign to monitor by [monitor spec](/docs/configuration/monitors#monitor-spec-format) (name, make, model, or serial) |
|
||||
| `tags` | integer | 1-9 | Assign to specific tag |
|
||||
| `no_force_center` | integer | `0` / `1` | Window does not force center |
|
||||
| `isnosizehint` | integer | `0` / `1` | Don't use min size and max size for size hints |
|
||||
|
||||
### Visuals & Decoration
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `noblur` | integer | `0` / `1` | Window does not have blur effect |
|
||||
| `isnoborder` | integer | `0` / `1` | Remove window border |
|
||||
| `isnoshadow` | integer | `0` / `1` | Not apply shadow |
|
||||
| `isnoradius` | integer | `0` / `1` | Not apply corner radius |
|
||||
| `isnoanimation` | integer | `0` / `1` | Not apply animation |
|
||||
| `focused_opacity` | integer | `0` / `1` | Window focused opacity |
|
||||
| `unfocused_opacity` | integer | `0` / `1` | Window unfocused opacity |
|
||||
| `allow_csd` | integer | `0` / `1` | Allow client side decoration |
|
||||
|
||||
> **Tip:** For detailed visual effects configuration, see the [Window Effects](/docs/visuals/effects) page for blur, shadows, and opacity settings.
|
||||
|
||||
### Layout & Scroller
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `scroller_proportion` | float | 0.1-1.0 | Set scroller proportion |
|
||||
| `scroller_proportion_single` | float | 0.1-1.0 | Set scroller auto adjust proportion when it is single window |
|
||||
|
||||
> **Tip:** For comprehensive layout configuration, see the [Layouts](/docs/window-management/layouts) page for all layout options and detailed settings.
|
||||
|
||||
### Animation
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `animation_type_open` | string | zoom, slide, fade, none | Set open animation |
|
||||
| `animation_type_close` | string | zoom, slide, fade, none | Set close animation |
|
||||
| `nofadein` | integer | `0` / `1` | Window ignores fade-in animation |
|
||||
| `nofadeout` | integer | `0` / `1` | Window ignores fade-out animation |
|
||||
|
||||
> **Tip:** For detailed animation configuration, see the [Animations](/docs/visuals/animations) page for available types and settings.
|
||||
|
||||
### Terminal & Swallowing
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `isterm` | integer | `0` / `1` | A new GUI window will replace the isterm window when it is opened |
|
||||
| `noswallow` | integer | `0` / `1` | The window will not replace the isterm window |
|
||||
|
||||
### Global & Special Windows
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `globalkeybinding` | string | `[mod combination][-][key]` | Global keybinding (only works for Wayland apps) |
|
||||
| `isunglobal` | integer | `0` / `1` | Open as unmanaged global window (for desktop pets or camera windows) |
|
||||
| `isnamedscratchpad` | integer | `0` / `1` | 0: disable, 1: named scratchpad |
|
||||
|
||||
> **Tip:** For scratchpad usage, see the [Scratchpad](/docs/window-management/scratchpad) page for detailed configuration examples.
|
||||
|
||||
### Performance & Tearing
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `force_tearing` | integer | `0` / `1` | Set window to tearing state, refer to [Tearing](/docs/configuration/monitors#tearing-game-mode) |
|
||||
|
||||
### Examples
|
||||
|
||||
```ini
|
||||
# Set specific window size and position
|
||||
windowrule=width:1000,height:900,appid:yesplaymusic,title:Demons
|
||||
|
||||
# Global keybindings for OBS Studio
|
||||
windowrule=globalkeybinding:ctrl+alt-o,appid:com.obsproject.Studio
|
||||
windowrule=globalkeybinding:ctrl+alt+n,appid:com.obsproject.Studio
|
||||
windowrule=isopensilent:1,appid:com.obsproject.Studio
|
||||
|
||||
# Force tearing for games
|
||||
windowrule=force_tearing:1,title:vkcube
|
||||
windowrule=force_tearing:1,title:Counter-Strike 2
|
||||
|
||||
# Named scratchpad for file manager
|
||||
windowrule=isnamedscratchpad:1,width:1280,height:800,appid:st-yazi
|
||||
|
||||
# Custom opacity for specific apps
|
||||
windowrule=focused_opacity:0.8,appid:firefox
|
||||
windowrule=unfocused_opacity:0.6,appid:foot
|
||||
|
||||
# Disable blur for selection tools
|
||||
windowrule=noblur:1,appid:slurp
|
||||
|
||||
# Position windows relative to screen center
|
||||
windowrule=offsetx:20,offsety:-30,width:800,height:600,appid:alacritty
|
||||
|
||||
# Send to specific tag and monitor
|
||||
windowrule=tags:9,monitor:HDMI-A-1,appid:discord
|
||||
|
||||
# Terminal swallowing setup
|
||||
windowrule=isterm:1,appid:st
|
||||
windowrule=noswallow:1,appid:foot
|
||||
|
||||
# Disable client-side decorations
|
||||
windowrule=allow_csd:1,appid:firefox
|
||||
|
||||
# Unmanaged global window (desktop pets, camera)
|
||||
windowrule=isunglobal:1,appid:cheese
|
||||
|
||||
# Named scratchpad toggle
|
||||
bind=alt,h,toggle_named_scratchpad,st-yazi,none,st -c st-yazi -e yazi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tag Rules
|
||||
|
||||
You can set all parameters in one line. If only `id` is set, the rule is followed when the id matches. If any of `monitor_name`, `monitor_make`, `monitor_model`, or `monitor_serial` are set, the rule is followed only if **all** of the set monitor fields match.
|
||||
|
||||
> **Warning:** Layouts set in tag rules have a higher priority than monitor rule layouts.
|
||||
|
||||
**Format:**
|
||||
|
||||
```ini
|
||||
tagrule=id:Values,Parameter:Values,Parameter:Values
|
||||
tagrule=id:Values,monitor_name:eDP-1,Parameter:Values,Parameter:Values
|
||||
tagrule=id:Values,monitor_make:xxx,monitor_model:xxx,Parameter:Values
|
||||
```
|
||||
|
||||
> **Tip:** See [Layouts](/docs/window-management/layouts#supported-layouts) for detailed descriptions of each layout type.
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `id` | integer | 0-9 | Match by tag id, 0 means the ~0 tag |
|
||||
| `monitor_name` | string | monitor name | Match by monitor name |
|
||||
| `monitor_make` | string | monitor make | Match by monitor manufacturer |
|
||||
| `monitor_model` | string | monitor model | Match by monitor model |
|
||||
| `monitor_serial` | string | monitor serial | Match by monitor serial number |
|
||||
| `layout_name` | string | layout name | Layout name to set |
|
||||
| `no_render_border` | integer | `0` / `1` | Disable render border |
|
||||
| `no_hide` | integer | `0` / `1` | Not hide even if the tag is empty |
|
||||
| `nmaster` | integer | 0, 99 | Number of master windows |
|
||||
| `mfact` | float | 0.1–0.9 | Master area factor |
|
||||
|
||||
### Examples
|
||||
|
||||
```ini
|
||||
# Set layout for specific tags
|
||||
tagrule=id:1,layout_name:scroller
|
||||
tagrule=id:2,layout_name:scroller
|
||||
|
||||
# Limit to specific monitor
|
||||
tagrule=id:1,monitor_name:eDP-1,layout_name:scroller
|
||||
tagrule=id:2,monitor_name:eDP-1,layout_name:scroller
|
||||
|
||||
# Persistent tags (1-4) with layout assignment
|
||||
tagrule=id:1,no_hide:1,layout_name:scroller
|
||||
tagrule=id:2,no_hide:1,layout_name:scroller
|
||||
tagrule=id:3,monitor_name:eDP-1,no_hide:1,layout_name:scroller
|
||||
tagrule=id:4,monitor_name:eDP-1,no_hide:1,layout_name:scroller
|
||||
|
||||
# Advanced tag configuration with master layout settings
|
||||
tagrule=id:5,layout_name:tile,nmaster:2,mfact:0.6
|
||||
tagrule=id:6,monitor_name:HDMI-A-1,layout_name:monocle,no_render_border:1
|
||||
```
|
||||
|
||||
> **Tip:** For Waybar configuration with persistent tags, see [Status Bar](/docs/visuals/status-bar) documentation.
|
||||
|
||||
---
|
||||
|
||||
## Layer Rules
|
||||
|
||||
You can set all parameters in one line. Target "layer shell" surfaces like status bars (`waybar`), launchers (`rofi`), or notification daemons.
|
||||
|
||||
**Format:**
|
||||
|
||||
```ini
|
||||
layerrule=layer_name:Values,Parameter:Values,Parameter:Values
|
||||
```
|
||||
|
||||
> **Tip:** You can use `mmsg -e` to get the last open layer name for debugging.
|
||||
|
||||
| Parameter | Type | Values | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `layer_name` | string | layer name | Match name of layer, supports regex |
|
||||
| `animation_type_open` | string | slide, zoom, fade, none | Set open animation |
|
||||
| `animation_type_close` | string | slide, zoom, fade, none | Set close animation |
|
||||
| `noblur` | integer | `0` / `1` | Disable blur |
|
||||
| `noanim` | integer | `0` / `1` | Disable layer animation |
|
||||
| `noshadow` | integer | `0` / `1` | Disable layer shadow |
|
||||
|
||||
> **Tip:** For animation types, see [Animations](/docs/visuals/animations#animation-types). For visual effects, see [Window Effects](/docs/visuals/effects).
|
||||
|
||||
### Examples
|
||||
|
||||
```ini
|
||||
# No blur or animation for slurp selection layer (avoids occlusion and ghosting in screenshots)
|
||||
layerrule=noanim:1,noblur:1,layer_name:selection
|
||||
|
||||
# Zoom animation for Rofi with multiple parameters
|
||||
layerrule=animation_type_open:zoom,noanim:0,layer_name:rofi
|
||||
|
||||
# Disable animations and shadows for notification daemon
|
||||
layerrule=noanim:1,noshadow:1,layer_name:swaync
|
||||
|
||||
# Multiple effects for launcher
|
||||
layerrule=animation_type_open:slide,animation_type_close:fade,noblur:1,layer_name:wofi
|
||||
```
|
||||
73
docs/window-management/scratchpad.md
Normal file
73
docs/window-management/scratchpad.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
title: Scratchpad
|
||||
description: Manage hidden "scratchpad" windows for quick access.
|
||||
---
|
||||
|
||||
mangowm supports two types of scratchpads: the standard pool (Sway-like) and named scratchpads.
|
||||
|
||||
## Standard Scratchpad
|
||||
|
||||
Any window can be sent to the "scratchpad" pile, which hides it. You can then cycle through them.
|
||||
|
||||
**Keybindings:**
|
||||
|
||||
```ini
|
||||
# Send current window to scratchpad
|
||||
bind=SUPER,i,minimized
|
||||
|
||||
# Toggle (show/hide) the scratchpad
|
||||
bind=ALT,z,toggle_scratchpad
|
||||
|
||||
# Retrieve window from scratchpad (restore)
|
||||
bind=SUPER+SHIFT,i,restore_minimized
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Named Scratchpad
|
||||
|
||||
Named scratchpads are bound to specific keys and applications. When triggered, mangowm will either launch the app (if not running) or toggle its visibility.
|
||||
|
||||
**1. Define the Window Rule**
|
||||
|
||||
You must identify the app using a unique `appid` or `title` and mark it as a named scratchpad. The application must support setting a custom appid or title at launch. Common examples:
|
||||
|
||||
- `st -c my-appid` — sets the appid
|
||||
- `kitty -T my-title` — sets the window title
|
||||
- `foot --app-id my-appid` — sets the appid
|
||||
|
||||
Use `none` as a placeholder when you only want to match by one field.
|
||||
|
||||
```ini
|
||||
# Match by appid
|
||||
windowrule=isnamedscratchpad:1,width:1280,height:800,appid:st-yazi
|
||||
|
||||
# Match by title
|
||||
windowrule=isnamedscratchpad:1,width:1000,height:700,title:kitty-scratch
|
||||
```
|
||||
|
||||
**2. Bind the Toggle Key**
|
||||
|
||||
Format: `bind=MOD,KEY,toggle_named_scratchpad,appid,title,command`
|
||||
|
||||
Use `none` for whichever field you are not matching on.
|
||||
|
||||
```ini
|
||||
# Match by appid: launch 'st' with class 'st-yazi' running 'yazi'
|
||||
bind=alt,h,toggle_named_scratchpad,st-yazi,none,st -c st-yazi -e yazi
|
||||
|
||||
# Match by title: launch 'kitty' with window title 'kitty-scratch'
|
||||
bind=alt,k,toggle_named_scratchpad,none,kitty-scratch,kitty -T kitty-scratch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Appearance
|
||||
|
||||
You can customize the size of scratchpad windows relative to the screen.
|
||||
|
||||
```ini
|
||||
scratchpad_width_ratio=0.8
|
||||
scratchpad_height_ratio=0.9
|
||||
scratchpadcolor=0x516c93ff
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue