Skip to content

customization.md

Latest commit

 

History

History
250 lines (173 loc) · 6.33 KB

customization.md

File metadata and controls

250 lines (173 loc) · 6.33 KB
Raw

Customization

How to extend, modify, and personalize bitzdots.

Understanding Auto-Generated Files

Files generated by wallust are marked with a DO NOT EDIT header. These include:

  • ~/.config/waybar/style.css
  • ~/.config/waybar/config.jsonc
  • ~/.config/swaync/style.css
  • ~/.config/wlogout/style.css
  • ~/.config/rofi/theme-generated.rasi
  • ~/.config/kitty/colors.conf
  • ~/.config/cava/themes/generated
  • ~/.config/hypr/hyprlock.conf
  • ~/.config/qt6ct/qt6ct.conf
  • ~/.config/kdeglobals

Editing these directly works, but your changes will be overwritten the next time you change your wallpaper.

Two Approaches to Customization

Option 1: Override Generated Files

Edit the generated file directly. Changes take effect immediately but are reset on the next wallpaper change.

Good for quick experiments or temporary tweaks.

Option 2: Edit the Templates (Permanent)

Edit the Jinja2 templates in ~/.config/wallust/templates/, then regenerate:

wallust run ~/.cache/current_wallpaper.png --config-dir ~/.config/wallust
~/.config/wallust/reload-theme.sh

Changes persist across all future wallpaper changes.

Customizing Waybar

Adding a Module

In waybar/config.jsonc (via template or override):

"custom/my-module": {
    "exec": "~/.config/waybar/scripts/my-script.sh",
    "interval": 10,
    "return-type": "json",
    "on-click": "command-to-run"
}

Add it to modules-left, modules-center, or modules-right.

Changing the Layout

Edit the modules-left, modules-center, modules-right arrays in waybar/config.jsonc.

Adding CSS

Edit waybar/style.css (or the waybar.css.j2 template for permanent changes).

Customizing Rofi

Adding a New Mode

Create a script in ~/.config/rofi/scripts/:

#!/bin/bash
# ~/.config/rofi/scripts/my-mode.sh
rofi -show my-mode -modes "my-mode:custom-script.sh"

Add a keybind in ~/.config/hypr/keybinds.lua:

hl.bind("SUPER + M", hl.dsp.exec_cmd("~/.config/rofi/scripts/my-mode.sh"))

Changing the Theme

Edit rofi-colors.rasi.j2 in the templates directory, or override theme-generated.rasi directly.

Adding a New Themed Component

To make a new app pick up colors from your wallpaper:

1. Create a Template

Create ~/.config/wallust/templates/myapp.conf.j2:

# MyApp config
background = {{background}}
foreground = {{foreground}}
accent = {{color1}}

2. Register in wallust.toml

Edit ~/.config/wallust/wallust.toml:

[myapp]
template = "myapp.conf.j2"
target = "~/.config/myapp/config"

3. Add to Reload Script

Edit ~/.config/wallust/reload-theme.sh to restart your app or reload its config.

4. Add to Cache Daemon

Add the target path to WALLUST_OUTPUTS in wallust-cache-daemon.sh so it's backed up and restored properly.

5. Regenerate

wallust run ~/.cache/current_wallpaper.png --config-dir ~/.config/wallust

Available Template Variables

All 16 colors from the wallust palette:

Variable Usage
{{background}} Main background
{{foreground}} Primary text
{{color0}} Terminal black (also background)
{{color1}} Primary accent
{{color2}} Green accent
{{color3}} Yellow accent
{{color4}} Blue accent
{{color5}} Magenta accent
{{color6}} Cyan accent
{{color7}} White (text)
{{color8}} Terminal bright black
{{color9}} Bright red
{{color10}} Bright green
{{color11}} Bright yellow
{{color12}} Bright blue
{{color13}} Bright magenta
{{color14}} Bright cyan
{{color15}} Bright white (also foreground)

Custom Keybindings

Edit ~/.config/hypr/keybinds.lua:

-- Add your own keybinds
hl.bind("SUPER + SHIFT + Z", hl.dsp.exec_cmd("your-command"))

Standard modifier syntax:

  • SUPER = Windows/Command key
  • SHIFT = Shift
  • CTRL = Control
  • ALT = Alt

Custom Wallpaper Directories

By default, bitzdots watches:

  • ~/Pictures/Wallpapers/ (static images)
  • ~/Pictures/Wallpapers/live/ (video files)

To add directories:

  1. Edit ~/.config/wallust/wallust-cache-daemon.sh
  2. Update the WATCH_DIRS array with new paths

Adding System TUI Tools

To add a new tool that opens in a floating terminal:

  1. Create a launcher script in ~/.config/waybar/scripts/:

    #!/bin/bash
kitty --class system-tui -e your-tui-tool

  2. The existing window rule in hypr/rules.lua auto-floats anything with class system-tui

  3. Wire it to a waybar click or keybind

Removing Components

To remove a waybar module

Remove it from the appropriate modules-* array in waybar/config.jsonc.

To disable the cache daemon

systemctl --user stop wallust-cache-daemon.service
systemctl --user disable wallust-cache-daemon.service

To switch terminal emulator

  1. Install your preferred terminal (e.g., foot, wezterm, alacritty)
  2. Update the terminal keybind in keybinds.lua
  3. If you want theming, create a wallust template for it

Dark Theme

bitzdots defaults to dark theme across all apps. This is configured at multiple levels:

GTK

  • ~/.config/gtk-3.0/settings.ini — Sets Adwaita theme with prefer-dark-theme=1 and Papirus-Dark icons
  • ~/.config/gtk-4.0/settings.ini — Same settings for GTK4

Qt

  • ~/.config/qt5ct/qt5ct.conf — Static config with Breeze-Dark style and Papirus-Dark icons
  • ~/.config/qt6ct/qt6ct.conf — Auto-generated by wallust with Breeze-Dark style and custom palette from your wallpaper
  • environment.d/qt.conf + hypr/variables.lua — Set QT_QPA_PLATFORMTHEME=qt6ct. QT_STYLE_OVERRIDE is intentionally NOT set (it overrides qt6ct and forces the light Breeze style).

Switching back to light theme

To switch all apps to light theme:

GTK:

# Edit ~/.config/gtk-3.0/settings.ini
# Change prefer-dark-theme=1 to prefer-dark-theme=0
# Change Papirus-Dark to Papirus

Qt:

# Edit ~/.config/qt5ct/qt5ct.conf
# Change style=Breeze-Dark to style=Breeze

# Edit ~/.config/qt6ct/qt6ct.conf
# Change style=Breeze-Dark to style=Breeze

Then log out and back in for changes to take effect. Do NOT set QT_STYLE_OVERRIDE=breeze — it forces light on Qt apps and qt6ct will warn.

Restoring Defaults

# Re-run the installer (links fresh configs)
cd ~/.config/bitzdots
./install.sh