504 lines
11 KiB
Markdown
504 lines
11 KiB
Markdown
---
|
|
name: zellij-config
|
|
description: "Comprehensive skill for managing Zellij terminal multiplexer configurations including setup, layouts, themes, keybindings, plugins, and web server configuration. Use this skill when users need to configure Zellij, create custom layouts, set up themes, manage keybindings, or configure web server access."
|
|
---
|
|
|
|
# Zellij Config
|
|
|
|
## Overview
|
|
|
|
This skill provides comprehensive Zellij terminal multiplexer configuration management. It enables users to set up Zellij from scratch, migrate configurations, create custom layouts and themes, manage keybindings, configure plugins, and set up web server access.
|
|
|
|
## Quick Start
|
|
|
|
Choose your configuration task:
|
|
|
|
1. **Setup Zellij** - Initialize configuration, create config directory, set basic settings
|
|
2. **Manage Layouts** - Create custom pane layouts, tab templates, swap layouts
|
|
3. **Configure Themes** - Set up custom themes, switch themes, convert theme formats
|
|
4. **Setup Keybindings** - Configure custom keybindings for different modes
|
|
5. **Plugin Management** - Load plugins, configure plugin aliases, set plugin options
|
|
6. **Web Server Setup** - Enable web access, configure SSL, set ports and IPs
|
|
|
|
## Setup Zellij
|
|
|
|
### Initialize Configuration Directory
|
|
|
|
Create Zellij configuration directory and dump default config:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/zellij
|
|
zellij setup --dump-config > ~/.config/zellij/config.kdl
|
|
```
|
|
|
|
### Validate Configuration
|
|
|
|
Check existing configuration for errors:
|
|
|
|
```bash
|
|
zellij setup --check
|
|
```
|
|
|
|
### Clean Start
|
|
|
|
Start Zellij with clean configuration (ignores existing config):
|
|
|
|
```bash
|
|
zellij --clean
|
|
```
|
|
|
|
### Configuration File Location
|
|
|
|
Specify custom configuration file:
|
|
|
|
```bash
|
|
zellij --config /path/to/custom/config.kdl
|
|
# or via environment variable
|
|
export ZELLIJ_CONFIG_FILE=/path/to/custom/config.kdl
|
|
```
|
|
|
|
## Manage Layouts
|
|
|
|
### Create Default Layout
|
|
|
|
Generate a default layout template:
|
|
|
|
```bash
|
|
zellij setup --dump-layout default > ~/.config/zellij/layouts/default.kdl
|
|
```
|
|
|
|
### Create Custom Layout
|
|
|
|
Create a development layout with multiple panes:
|
|
|
|
```kdl
|
|
layout {
|
|
default_tab_template {
|
|
pane size=1 borderless=true {
|
|
plugin location="zellij:tab-bar"
|
|
}
|
|
children
|
|
pane size=2 borderless=true {
|
|
plugin location="zellij:status-bar"
|
|
}
|
|
}
|
|
tab name="development" split_direction="vertical" {
|
|
pane size="70%" {
|
|
command "nvim"
|
|
cwd "~/project"
|
|
}
|
|
pane split_direction="horizontal" {
|
|
pane command="git" {
|
|
args "status"
|
|
cwd "~/project"
|
|
}
|
|
pane command="htop"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Floating Layout Example
|
|
|
|
Layout with floating panes for different pane counts:
|
|
|
|
```kdl
|
|
layout {
|
|
swap_floating_layout {
|
|
floating_panes max_panes=1 {
|
|
pane
|
|
}
|
|
floating_panes max_panes=2 {
|
|
pane x=0
|
|
pane x="50%"
|
|
}
|
|
floating_panes max_panes=3 {
|
|
pane x=0 width="25%"
|
|
pane x="25%" width="25%"
|
|
pane x="50%"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Use Custom Layout
|
|
|
|
Load a specific layout:
|
|
|
|
```bash
|
|
zellij --layout /path/to/custom-layout.kdl
|
|
# or place in ~/.config/zellij/layouts/ and use default
|
|
```
|
|
|
|
## Configure Themes
|
|
|
|
### Apply Built-in Theme
|
|
|
|
Set theme in configuration file:
|
|
|
|
```kdl
|
|
theme "default"
|
|
```
|
|
|
|
### Define Custom Theme (RGB)
|
|
|
|
Create a custom theme with RGB values:
|
|
|
|
```kdl
|
|
themes {
|
|
custom_theme {
|
|
fg 248 248 242
|
|
bg 40 42 54
|
|
black 0 0 0
|
|
red 255 85 85
|
|
green 80 250 123
|
|
yellow 241 250 140
|
|
blue 98 114 164
|
|
magenta 255 121 198
|
|
cyan 139 233 253
|
|
white 255 255 255
|
|
orange 255 184 108
|
|
}
|
|
}
|
|
```
|
|
|
|
### Define Custom Theme (Hexadecimal)
|
|
|
|
Create a theme with hex color codes:
|
|
|
|
```kdl
|
|
themes {
|
|
nord {
|
|
fg "#D8DEE9"
|
|
bg "#2E3440"
|
|
black "#3B4252"
|
|
red "#BF616A"
|
|
green "#A3BE8C"
|
|
yellow "#EBCB8B"
|
|
blue "#81A1C1"
|
|
magenta "#B48EAD"
|
|
cyan "#88C0D0"
|
|
white "#E5E9F0"
|
|
orange "#D08770"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Switch Theme from Command Line
|
|
|
|
Temporarily use a theme:
|
|
|
|
```bash
|
|
zellij --theme custom_theme
|
|
```
|
|
|
|
### Convert Legacy Theme
|
|
|
|
Convert YAML theme to KDL format:
|
|
|
|
```bash
|
|
zellij convert-theme /path/to/old-theme.yaml > /path/to/new-theme.kdl
|
|
```
|
|
|
|
## Setup Keybindings
|
|
|
|
### Basic Keybinding Configuration
|
|
|
|
Configure keybindings for different modes:
|
|
|
|
```kdl
|
|
keybinds {
|
|
normal {
|
|
bind "Ctrl g" { SwitchToMode "locked"; }
|
|
bind "Ctrl p" { SwitchToMode "pane"; }
|
|
bind "Alt n" { NewPane; }
|
|
bind "Alt h" "Alt Left" { MoveFocusOrTab "Left"; }
|
|
bind "Ctrl Shift t" { NewTab; }
|
|
}
|
|
pane {
|
|
bind "h" "Left" { MoveFocus "Left"; }
|
|
bind "l" "Right" { MoveFocus "Right"; }
|
|
bind "j" "Down" { MoveFocus "Down"; }
|
|
bind "k" "Up" { MoveFocus "Up"; }
|
|
bind "p" { SwitchFocus; }
|
|
bind "Ctrl c" { CopySelection; }
|
|
}
|
|
locked {
|
|
bind "Ctrl g" { SwitchToMode "normal"; }
|
|
}
|
|
shared {
|
|
bind "Alt 1" { Run "git" "status"; }
|
|
bind "Alt 2" { Run "git" "diff"; }
|
|
bind "Alt 3" { Run "exa" "--color" "always"; }
|
|
}
|
|
}
|
|
```
|
|
|
|
### Keybinding Syntax Examples
|
|
|
|
Different keybinding syntax patterns:
|
|
|
|
```kdl
|
|
bind "a" // individual character
|
|
bind "Ctrl a" // with ctrl modifier
|
|
bind "Alt a" // with alt modifier
|
|
bind "Ctrl Alt a" // multiple modifiers
|
|
bind "F8" // function key
|
|
bind "Left" // arrow key
|
|
```
|
|
|
|
## Plugin Management
|
|
|
|
### Load Plugins on Startup
|
|
|
|
Configure plugins to load automatically:
|
|
|
|
```kdl
|
|
load_plugins {
|
|
https://example.com/my-plugin.wasm
|
|
file:/path/to/my/plugin.kdl
|
|
my-plugin-alias
|
|
}
|
|
```
|
|
|
|
### Configure Plugin Aliases
|
|
|
|
Set up common plugin aliases:
|
|
|
|
```kdl
|
|
plugins {
|
|
tab-bar location="zellij:tab-bar"
|
|
status-bar location="zellij:status-bar"
|
|
strider location="zellij:strider"
|
|
compact-bar location="zellij:compact-bar"
|
|
session-manager location="zellij:session-manager"
|
|
welcome-screen location="zellij:session-manager" {
|
|
welcome_screen true
|
|
}
|
|
filepicker location="zellij:strider" {
|
|
cwd "/"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Configure Plugin Options
|
|
|
|
Pass configuration to plugins:
|
|
|
|
```kdl
|
|
layout {
|
|
pane {
|
|
plugin location="file:/path/to/my/plugin.wasm" {
|
|
some_key "some_value"
|
|
another_key 1
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Launch Plugin with Configuration
|
|
|
|
Configure plugin via command line:
|
|
|
|
```bash
|
|
zellij action launch-or-focus-plugin --configuration "some_key=some_value,another_key=1"
|
|
```
|
|
|
|
## Web Server Setup
|
|
|
|
### Enable Web Server
|
|
|
|
Start web server automatically:
|
|
|
|
```kdl
|
|
web_server true
|
|
web_server_ip "0.0.0.0"
|
|
web_server_port 8082
|
|
```
|
|
|
|
### Configure SSL
|
|
|
|
Set up HTTPS with SSL certificates:
|
|
|
|
```kdl
|
|
web_server true
|
|
web_server_ip "0.0.0.0"
|
|
web_server_port 443
|
|
web_server_cert "/path/to/my/certs/localhost+3.pem"
|
|
web_server_key "/path/to/my/certs/localhost+3-key.pem"
|
|
enforce_https_on_localhost true
|
|
```
|
|
|
|
### Web Client Configuration
|
|
|
|
Configure browser-based terminal appearance:
|
|
|
|
```kdl
|
|
web_client {
|
|
font "Iosevka Term"
|
|
cursor_blink true
|
|
cursor_style "block"
|
|
cursor_inactive_style "outline"
|
|
mac_option_is_meta false
|
|
theme {
|
|
background 10 20 30
|
|
foreground 10 20 30
|
|
black 10 20 30
|
|
blue 10 20 30
|
|
bright_black 10 20 30
|
|
bright_blue 10 20 30
|
|
bright_cyan 10 20 30
|
|
bright_green 10 20 30
|
|
bright_magenta 10 20 30
|
|
bright_red 10 20 30
|
|
bright_white 10 20 30
|
|
bright_yellow 10 20 30
|
|
cursor 10 20 30
|
|
cursor_accent 10 20 30
|
|
cyan 10 20 30
|
|
green 10 20 30
|
|
magenta 10 20 30
|
|
red 10 20 30
|
|
white 10 20 30
|
|
yellow 10 20 30
|
|
selection_background 10 20 30
|
|
selection_foreground 10 20 30
|
|
selection_inactive_background 10 20 30
|
|
}
|
|
}
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
### Set Environment for Panes
|
|
|
|
Configure environment variables for all panes:
|
|
|
|
```kdl
|
|
env {
|
|
RUST_BACKTRACE 1
|
|
FOO "bar"
|
|
EDITOR "nvim"
|
|
}
|
|
```
|
|
|
|
### Session Management
|
|
|
|
Configure session persistence and resurrection:
|
|
|
|
```kdl
|
|
session_serialization true
|
|
pane_viewport_serialization true
|
|
scrollback_lines_to_serialize 0
|
|
default_layout "compact"
|
|
default_mode "locked"
|
|
```
|
|
|
|
## Common Workflows
|
|
|
|
### Development Environment Setup
|
|
|
|
Create a comprehensive development layout:
|
|
|
|
```bash
|
|
# Create development layout
|
|
cat > ~/.config/zellij/layouts/dev.kdl << 'EOF'
|
|
layout {
|
|
default_tab_template {
|
|
pane size=1 borderless=true {
|
|
plugin location="zellij:tab-bar"
|
|
}
|
|
children
|
|
pane size=2 borderless=true {
|
|
plugin location="zellij:status-bar"
|
|
}
|
|
}
|
|
tab name="editor" cwd="~/project" focus=true {
|
|
pane command="nvim" size="80%"
|
|
pane size="20%" split_direction="vertical" {
|
|
pane command="git" {
|
|
args "status"
|
|
size="50%"
|
|
}
|
|
pane command="htop"
|
|
}
|
|
}
|
|
tab name="terminal" {
|
|
pane command="bash"
|
|
}
|
|
tab name="monitoring" split_direction="horizontal" {
|
|
pane command="htop"
|
|
pane command="btop"
|
|
}
|
|
}
|
|
EOF
|
|
|
|
# Use the layout
|
|
zellij --layout dev
|
|
```
|
|
|
|
### Multiplayer Session Setup
|
|
|
|
Configure colors for multiplayer sessions:
|
|
|
|
```kdl
|
|
multiplayer_user_colors {
|
|
player_1 255 0 255
|
|
player_2 0 217 227
|
|
player_3 0
|
|
player_4 255 230 0
|
|
player_5 0 229 229
|
|
player_6 0
|
|
player_7 255 53 94
|
|
player_8 0
|
|
player_9 0
|
|
player_10 0
|
|
}
|
|
```
|
|
|
|
## Configuration Validation
|
|
|
|
### Check Configuration
|
|
|
|
Validate configuration file syntax:
|
|
|
|
```bash
|
|
zellij setup --check
|
|
```
|
|
|
|
### Test Configuration
|
|
|
|
Test new configuration without affecting existing session:
|
|
|
|
```bash
|
|
zellij --config /path/to/test-config.kdl --session-name test-session
|
|
```
|
|
|
|
## Resources
|
|
|
|
### scripts/
|
|
Executable scripts for Zellij configuration management:
|
|
|
|
- `setup_zellij.py` - Automates initial Zellij setup
|
|
- `create_layout.py` - Generates custom layouts from templates
|
|
- `convert_themes.py` - Converts legacy theme formats to KDL
|
|
- `validate_config.py` - Validates Zellij configuration syntax
|
|
- `backup_config.py` - Creates configuration backups
|
|
|
|
### references/
|
|
Comprehensive Zellij configuration documentation:
|
|
|
|
- `configuration_options.md` - Complete reference of all Zellij options
|
|
- `layout_examples.md` - Collection of layout templates
|
|
- `theme_examples.md` - Custom theme examples and guidelines
|
|
- `keybinding_reference.md` - Complete keybinding syntax and actions
|
|
- `plugin_api.md` - Plugin development and configuration guide
|
|
|
|
### assets/
|
|
Configuration templates and example files:
|
|
|
|
- `config_templates/` - Starter configuration files for different use cases
|
|
- `layout_templates/` - Common layout templates (development, monitoring, etc.)
|
|
- `theme_templates/` - Custom theme files (nord, dracula, etc.)
|
|
- `plugin_examples/` - Example plugin configurations
|