From 9ad87a84a234d298139da70dbdc009141e006103 Mon Sep 17 00:00:00 2001 From: Samuel Onoja Date: Wed, 30 Sep 2026 07:05:18 +0100 Subject: [PATCH] improve docs --- README.md | 10 +-- docs/configuration.md | 5 +- packaging/config.kdl | 160 ++++++++++++++++++++++++++++++++++++++++-- site/content/index.md | 11 +-- 4 files changed, 171 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 256d7f4..e2ea560 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ See the [configuration reference](docs/configuration.md) and `Super` is usually the Windows key. Change shortcuts and gestures in **Settings → Shortcuts**. -| Shortcut | Action | +| Control | Action | | --- | --- | | Super + Enter | Open a terminal | | Super + H / J / K / L | Focus left / down / up / right | @@ -69,13 +69,15 @@ See the [configuration reference](docs/configuration.md) and | Print Screen | Capture the active monitor and open Satty | | Super + Shift + S | Select a screenshot area | | Super + Shift + E | Ask to log out | +| Super + left-button drag | Move a floating window | +| Super + right-button drag | Resize a floating window | +| Three-finger swipe up / down | Next / previous workspace | +| Three-finger swipe left / right | Focus the window to the right / left | +| Login shortcut guide | Appears at login; disable in Settings → Shortcuts | See [all shortcuts and mouse actions](docs/shortcuts.md), including Super-drag to move and Super-right-drag to resize floating windows. -Three-finger swipes up/down switch workspaces; left/right focus windows. -The shortcut guide appears at login until disabled in Settings. - ## Documentation Start with the [documentation index](docs/README.md) for user guides and diff --git a/docs/configuration.md b/docs/configuration.md index 74ee86e..4a4b64c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,7 +1,10 @@ # Configuration Edit `~/.config/ferese/config.kdl` (or `$XDG_CONFIG_HOME/ferese/config.kdl`), -or open **Control Center → Settings**. Start with the [example](../packaging/config.kdl). +or open **Control Center → Settings**. Start with the [example](../packaging/config.kdl), +which includes app and media shortcuts, appearance, widgets, and optional startup +and display settings. Its browser/editor shortcuts need Firefox/Zed; brightness +keys need `brightnessctl` and audio keys need `wpctl`. This reference covers layouts, appearance, input, and desktop behavior. See [Desktop widgets](desktop-widgets.md), [Notifications](notifications.md), and [Desktop portals](portals.md) for their additional options. diff --git a/packaging/config.kdl b/packaging/config.kdl index 2bb6cfb..10e7950 100644 --- a/packaging/config.kdl +++ b/packaging/config.kdl @@ -1,25 +1,129 @@ +// Commands run directly, without a shell. Install optional apps before using them. commands { terminal "foot" + browser "firefox" + editor "zed" + lock "ferese-lock" screenshot "ferese-screenshot" screenshot-full "ferese-screenshot" "--full" + + brightness-up "brightnessctl" "set" "2%+" + brightness-down "brightnessctl" "set" "2%-" + volume-up "wpctl" "set-volume" "-l" "1.0" "@DEFAULT_AUDIO_SINK@" "5%+" + volume-down "wpctl" "set-volume" "-l" "1.0" "@DEFAULT_AUDIO_SINK@" "5%-" + mute "wpctl" "set-mute" "@DEFAULT_AUDIO_SINK@" "toggle" + mic-mute "wpctl" "set-mute" "@DEFAULT_AUDIO_SOURCE@" "toggle" } +// These supplement the built-in shortcuts listed in docs/shortcuts.md. +binding "Super+B" "spawn" "browser" +binding "Super+Z" "spawn" "editor" +binding "Super+Alt+L" "spawn" "lock" +binding "XF86MonBrightnessUp" "spawn" "brightness-up" +binding "XF86MonBrightnessDown" "spawn" "brightness-down" +binding "XF86AudioRaiseVolume" "spawn" "volume-up" +binding "XF86AudioLowerVolume" "spawn" "volume-down" +binding "XF86AudioMute" "spawn" "mute" +binding "XF86AudioMicMute" "spawn" "mic-mute" + +binding "Super+Left" "focus" "left" +binding "Super+Down" "focus" "down" +binding "Super+Up" "focus" "up" +binding "Super+Right" "focus" "right" +binding "Super+Ctrl+Left" "move" "left" +binding "Super+Ctrl+Down" "move" "down" +binding "Super+Ctrl+Up" "move" "up" +binding "Super+Ctrl+Right" "move" "right" +binding "Super+Alt+Left" "resize" "left" +binding "Super+Alt+Down" "resize" "down" +binding "Super+Alt+Up" "resize" "up" +binding "Super+Alt+Right" "resize" "right" + +// Replace a swipe action with "toggle-overview", "move" "left", or another action. +binding "Swipe3Up" "workspace-next" +binding "Swipe3Down" "workspace-previous" +binding "Swipe3Left" "focus" "right" +binding "Swipe3Right" "focus" "left" + input { xkb-layout "us" + xkb-variant "" + xkb-options focus-follows-mouse #false + repeat-rate 25 + repeat-delay-ms 600 touchpad { + tap #true + natural-scroll #true + disable-while-typing #true swipe-threshold 80 } } layout { + mode "scrolling" + inner-gap 4 + outer-gap 4 smart-gaps #false } +scrolling { + default-column-width 0.5 + focus-strategy "paged" + width-presets 0.33333 0.5 0.66667 "full" +} + +animations { + enabled #true + reduced-motion #false + speed 0.9 +} + +appearance { + inactive-dim { + enabled #false + amount 0.15 + duration-ms 150 + } +} + theme { + background { + mode "fill" + // path "/absolute/path/to/wallpaper.png" + } + colors { + accent "#3D7BE6" + surface-base "#111821" + text-primary "#F4F7FB" + text-muted "#8793A2" + border "#FFFFFF18" + shadow "#00000055" + } material { - opacity 0.95 + style "translucent" + opacity 0.78 + blur-radius 25 + } + geometry { + window-radius 12 + shell-radius 12 + border-width 1 + focus-ring-width 1 + top-bar-height 30 + top-bar-margin-horizontal 18 + top-bar-margin-top 6 + top-bar-window-gap 4 + panel-padding 12 + control-gap 12 + } + shadow { + soft { + blur 10 + offset-y 2 + opacity 0.07 + } } surface { bar { @@ -28,23 +132,49 @@ theme { text-muted "#8793A2" } } + // typography { font-family "JetBrainsMono Nerd Font"; } +} + +status { + keybinding-guide #true + window-title #true + battery-percentage #true + low-battery-threshold 20 } window-rule app-id="dev.ferese.Settings" floating=#true window-rule app-id="dev.ferese.ScreenShare" floating=#true +window-rule app-id="dev.ferese.Authentication" floating=#true +window-rule app-id="org.gnome.Calculator" floating=#true +window-rule app-id="org.pulseaudio.pavucontrol" floating=#true +window-rule title="Picture-in-Picture" floating=#true window-rule title="Choose a wallpaper" floating=#true desktop-widgets { - clock { + clock enabled=#false { style "pixel" - enabled #false anchor "top_left" margin-x 64 margin-y 80 - time-size 128.0 - date-size 18.0 + width 440 + height 320 + time-size 128 + date-size 18 + time-format "%H:%M" + date-format "%a, %b %-d" + show-date #true opacity 0.9 } + note "today" enabled=#false { + title "Today" + text "Review the project\nTake a break" + anchor "top_right" + margin-x 48 + margin-y 80 + width 320 + height 240 + text-size 16 + } } notifications { @@ -52,3 +182,23 @@ notifications { do-not-disturb #false timeout-ms 6000 } + +lock-screen { + clock-format "12h" + background-dim 0.26 + background-blur 14 + dim-after-seconds 30 + sleep-after-seconds 120 +} + +// Install swayidle and test unlocking before enabling automatic locking. +// autostart "swayidle" "-w" "timeout" "300" "ferese-lock" "before-sleep" "ferese-lock" "lock" "ferese-lock" + +// Find display names with feresectl get-outputs, then adjust and uncomment. +// output-profile "docked" { +// output "HDMI-A-1" scale=1.5 { position 0 0; } +// output "eDP-1" scale=1.5 { position 2560 0; } +// } +// output-profile "laptop" { +// output "eDP-1" scale=1.5 +// } diff --git a/site/content/index.md b/site/content/index.md index 5551c19..66993fe 100644 --- a/site/content/index.md +++ b/site/content/index.md @@ -13,7 +13,7 @@ windows, and a shared theme for its desktop tools. `Super` is usually the Windows key. All these shortcuts can be changed in Settings. -| Shortcut | Action | +| Control | Action | | --- | --- | | Super + Enter | Open a terminal | | Super + H / J / K / L | Focus left / down / up / right | @@ -24,14 +24,15 @@ windows, and a shared theme for its desktop tools. | Print Screen | Capture the active monitor and open Satty | | Super + Shift + S | Select a screenshot area | | Super + Shift + E | Ask to log out | +| Super + left-button drag | Move a floating window | +| Super + right-button drag | Resize a floating window | +| Three-finger swipe up / down | Next / previous workspace | +| Three-finger swipe left / right | Focus the window to the right / left | +| Login shortcut guide | Appears at login; disable in Settings → Shortcuts | See [all shortcuts and mouse actions](shortcuts.md), including Super-drag to move and Super-right-drag to resize floating windows. -Three-finger swipes up/down switch workspaces; left/right focus windows. -Change gestures in **Settings → Shortcuts**. The login shortcut guide can be -disabled there too. - ## Desktop guides - [Desktop widgets](desktop-widgets.md): clocks and sticky notes.