bitzdots

gitlab
Lean Hyprland dotfiles with automatic matugen theming. Low-end optimized, full-stack auto-coloring, 26 Jinja2 templates. Rofi-powered menus, waybar modules, screenshot/recording, event-driven cache daemon.
0 stars0 forksupdated 2d agodefault branch: matugenExtended
Download .tar.gz View on gitlab ↗View on github ↗
clonehttps://gitlab.com/bitzzdev/bitzdots.git
archlinuxdotfileshyprlandhyprland-dotfileslow-endminimalricingwallustwaybarwayland
@ matugenExtended
6.3 KBtext
Raw View on gitlab ↗
1# Customization
2 
3How to extend, modify, and personalize bitzdots.
4 
5## Understanding Auto-Generated Files
6 
7Files generated by matugen are marked with a `DO NOT EDIT` header. These include:
8 
9- `~/.config/waybar/style.css`
10- `~/.config/waybar/config.jsonc`
11- `~/.config/swaync/style.css`
12- `~/.config/wlogout/style.css`
13- `~/.config/rofi/theme-generated.rasi`
14- `~/.config/kitty/colors.conf`
15- `~/.config/cava/themes/generated`
16- `~/.config/hypr/hyprlock.conf`
17- `~/.config/qt6ct/qt6ct.conf`
18- `~/.config/kdeglobals`
19 
20**Editing these directly works**, but your changes will be overwritten the next time you change your wallpaper.
21 
22## Two Approaches to Customization
23 
24### Option 1: Override Generated Files
25 
26Edit the generated file directly. Changes take effect immediately but are reset on the next wallpaper change.
27 
28Good for quick experiments or temporary tweaks.
29 
30### Option 2: Edit the Templates (Permanent)
31 
32Edit the Jinja2 templates in `~/.config/matugen/templates/`, then regenerate:
33 
34```bash
35matugen image ~/.cache/current_wallpaper.png --config ~/.config/matugen/config.toml
36~/.config/matugen/reload-theme.sh
37```
38 
39Changes persist across all future wallpaper changes.
40 
41## Customizing Waybar
42 
43### Adding a Module
44 
45In `waybar/config.jsonc` (via template or override):
46 
47```jsonc
48"custom/my-module": {
49    "exec": "~/.config/waybar/scripts/my-script.sh",
50    "interval": 10,
51    "return-type": "json",
52    "on-click": "command-to-run"
53}
54```
55 
56Add it to `modules-left`, `modules-center`, or `modules-right`.
57 
58### Changing the Layout
59 
60Edit the `modules-left`, `modules-center`, `modules-right` arrays in `waybar/config.jsonc`.
61 
62### Adding CSS
63 
64Edit `waybar/style.css` (or the `waybar.css.j2` template for permanent changes).
65 
66## Customizing Rofi
67 
68### Adding a New Mode
69 
70Create a script in `~/.config/rofi/scripts/`:
71 
72```bash
73#!/bin/bash
74# ~/.config/rofi/scripts/my-mode.sh
75rofi -show my-mode -modes "my-mode:custom-script.sh"
76```
77 
78Add a keybind in `~/.config/hypr/keybinds.lua`:
79```lua
80hl.bind("SUPER + M", hl.dsp.exec_cmd("~/.config/rofi/scripts/my-mode.sh"))
81```
82 
83### Changing the Theme
84 
85Edit `rofi-colors.rasi.j2` in the templates directory, or override `theme-generated.rasi` directly.
86 
87## Adding a New Themed Component
88 
89To make a new app pick up colors from your wallpaper:
90 
91### 1. Create a Template
92 
93Create `~/.config/matugen/templates/myapp.conf.j2`:
94 
95```jinja2
96# MyApp config
97background = {{background}}
98foreground = {{foreground}}
99accent = {{color1}}
100```
101 
102### 2. Register in config.toml
103 
104Edit `~/.config/matugen/config.toml`:
105 
106```toml
107[myapp]
108template = "myapp.conf.j2"
109target = "~/.config/myapp/config"
110```
111 
112### 3. Add to Reload Script
113 
114Edit `~/.config/matugen/reload-theme.sh` to restart your app or reload its config.
115 
116### 4. Add to Cache Daemon
117 
118Add the target path to `MATUGEN_OUTPUTS` in `matugen-cache-daemon.sh` so it's backed up and restored properly.
119 
120### 5. Regenerate
121 
122```bash
123matugen image ~/.cache/current_wallpaper.png --config ~/.config/matugen/config.toml
124```
125 
126## Available Template Variables
127 
128All 16 colors from the matugen palette:
129 
130| Variable | Usage |
131|----------|-------|
132| `{{background}}` | Main background |
133| `{{foreground}}` | Primary text |
134| `{{color0}}` | Terminal black (also background) |
135| `{{color1}}` | Primary accent |
136| `{{color2}}` | Green accent |
137| `{{color3}}` | Yellow accent |
138| `{{color4}}` | Blue accent |
139| `{{color5}}` | Magenta accent |
140| `{{color6}}` | Cyan accent |
141| `{{color7}}` | White (text) |
142| `{{color8}}` | Terminal bright black |
143| `{{color9}}` | Bright red |
144| `{{color10}}` | Bright green |
145| `{{color11}}` | Bright yellow |
146| `{{color12}}` | Bright blue |
147| `{{color13}}` | Bright magenta |
148| `{{color14}}` | Bright cyan |
149| `{{color15}}` | Bright white (also foreground) |
150 
151## Custom Keybindings
152 
153Edit `~/.config/hypr/keybinds.lua`:
154 
155```lua
156-- Add your own keybinds
157hl.bind("SUPER + SHIFT + Z", hl.dsp.exec_cmd("your-command"))
158```
159 
160Standard modifier syntax:
161- `SUPER` = Windows/Command key
162- `SHIFT` = Shift
163- `CTRL` = Control  
164- `ALT` = Alt
165 
166## Custom Wallpaper Directories
167 
168By default, bitzdots watches:
169- `~/Pictures/Wallpapers/` (static images)
170- `~/Pictures/Wallpapers/live/` (video files)
171 
172To add directories:
1731. Edit `~/.config/matugen/matugen-cache-daemon.sh`
1742. Update the `WATCH_DIRS` array with new paths
175 
176## Adding System TUI Tools
177 
178To add a new tool that opens in a floating terminal:
179 
1801. Create a launcher script in `~/.config/waybar/scripts/`:
181   ```bash
182   #!/bin/bash
183   kitty --class system-tui -e your-tui-tool
184   ```
185 
1862. The existing window rule in `hypr/rules.lua` auto-floats anything with class `system-tui`
187 
1883. Wire it to a waybar click or keybind
189 
190## Removing Components
191 
192### To remove a waybar module
193 
194Remove it from the appropriate `modules-*` array in `waybar/config.jsonc`.
195 
196### To disable the cache daemon
197 
198```bash
199systemctl --user stop matugen-cache-daemon.service
200systemctl --user disable matugen-cache-daemon.service
201```
202 
203### To switch terminal emulator
204 
2051. Install your preferred terminal (e.g., `foot`, `wezterm`, `alacritty`)
2062. Update the terminal keybind in `keybinds.lua`
2073. If you want theming, create a matugen template for it
208 
209## Dark Theme
210 
211bitzdots defaults to dark theme across all apps. This is configured at multiple levels:
212 
213### GTK
214- `~/.config/gtk-3.0/settings.ini` — Sets `Adwaita` theme with `prefer-dark-theme=1` and `Papirus-Dark` icons
215- `~/.config/gtk-4.0/settings.ini` — Same settings for GTK4
216 
217### Qt
218- `~/.config/qt5ct/qt5ct.conf` — Static config with `Breeze-Dark` style and `Papirus-Dark` icons
219- `~/.config/qt6ct/qt6ct.conf` — Auto-generated by matugen with `Breeze-Dark` style and custom palette from your wallpaper
220- `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).
221 
222### Switching back to light theme
223 
224To switch all apps to light theme:
225 
226**GTK:**
227```bash
228# Edit ~/.config/gtk-3.0/settings.ini
229# Change prefer-dark-theme=1 to prefer-dark-theme=0
230# Change Papirus-Dark to Papirus
231```
232 
233**Qt:**
234```bash
235# Edit ~/.config/qt5ct/qt5ct.conf
236# Change style=Breeze-Dark to style=Breeze
237 
238# Edit ~/.config/qt6ct/qt6ct.conf
239# Change style=Breeze-Dark to style=Breeze
240```
241 
242Then 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.
243 
244## Restoring Defaults
245 
246```bash
247# Re-run the installer (links fresh configs)
248cd ~/.config/bitzdots
249./install.sh
250```
251