feat(home): mkDefault behaviour settings so downstream can plain-override
Nomarchy's Hyprland/Ghostty/Waybar settings were set at normal priority, so a downstream `home.nix` setting any value Nomarchy already set threw a "conflicting definition values" error — overriding required lib.mkForce, contradicting the README's "mkDefault throughout" claim. Now: behaviour/chrome leaves (input, misc, monitor, animations, dwindle, gesture, decoration.blur sizing, ghostty padding/decoration, waybar settings+style) are lib.mkDefault — a plain home.nix assignment wins. Appearance values that flow from theme-state.json (gaps, colors, rounding, opacity, fonts) stay at normal priority on purpose: change them via nomarchy-theme-sync (their source of truth) or lib.mkForce to hardcode. bind/exec-once lists stay normal priority so additions concatenate rather than replace. Verified: behaviour/ghostty plain overrides build; theme values still conflict (steering to the CLI); default rendered config is byte-identical. New docs/OVERRIDES.md with the appearance→CLI / behaviour→home.nix / component→toggle model and worked examples; linked from the README. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Bernardo Magri
147
docs/OVERRIDES.md
Normal file
147
docs/OVERRIDES.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Overriding Nomarchy's defaults
|
||||
|
||||
You consume Nomarchy as a flake input and own two files: `system.nix` and
|
||||
`home.nix`. Your config is **merged** with Nomarchy's modules, so changing a
|
||||
default is just a matter of knowing which of three knobs to reach for. The
|
||||
rule of thumb:
|
||||
|
||||
> **Appearance → the CLI. Behaviour → `home.nix`. Whole component → toggle it off.**
|
||||
|
||||
## 1. Appearance (gaps, colors, rounding, fonts, opacity) — use the CLI
|
||||
|
||||
Everything that defines the *look* flows from `theme-state.json`, the single
|
||||
source of truth. Change it with `nomarchy-theme-sync`, which writes the JSON
|
||||
and rebuilds — one generation, applied to Hyprland, Waybar, Ghostty, btop and
|
||||
Stylix at once:
|
||||
|
||||
```sh
|
||||
nomarchy-theme-sync set ui.gapsOut 16 # gaps, borders, rounding, opacity
|
||||
nomarchy-theme-sync set ui.rounding 0
|
||||
nomarchy-theme-sync set fonts.mono "FiraCode Nerd Font"
|
||||
nomarchy-theme-sync apply gruvbox # whole palette
|
||||
```
|
||||
|
||||
These values are deliberately kept at normal priority in the modules, so they
|
||||
stay owned by the theme system. If you *insist* on pinning one in `home.nix`
|
||||
regardless of the active theme, use `lib.mkForce` (see §4) — but then the CLI
|
||||
can no longer change that knob.
|
||||
|
||||
## 2. Behaviour (input, misc, monitor, animations, terminal chrome) — `home.nix`
|
||||
|
||||
Non-appearance defaults are set with `lib.mkDefault`, so a **plain assignment**
|
||||
in your `home.nix` wins — no `mkForce` needed:
|
||||
|
||||
```nix
|
||||
# home.nix
|
||||
{ ... }:
|
||||
{
|
||||
wayland.windowManager.hyprland.settings = {
|
||||
input.follow_mouse = 0; # was 1
|
||||
input.touchpad.natural_scroll = false;
|
||||
misc.disable_splash_rendering = false;
|
||||
monitor = [ "DP-1,2560x1440@144,0x0,1" ]; # replaces the default rule
|
||||
animations.enabled = false;
|
||||
};
|
||||
|
||||
programs.ghostty.settings = {
|
||||
window-padding-x = 4; # was 12
|
||||
window-decoration = true;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Adding vs. overriding lists
|
||||
|
||||
`bind`, `bindel`, `bindl`, `bindm` and `exec-once` are lists kept at normal
|
||||
priority, so anything you add **concatenates** with Nomarchy's — your binds and
|
||||
autostarts run *alongside* the defaults:
|
||||
|
||||
```nix
|
||||
{
|
||||
wayland.windowManager.hyprland.settings = {
|
||||
bind = [
|
||||
"$mod, B, exec, firefox"
|
||||
"$mod SHIFT, S, exec, grim -g \"$(slurp)\" - | swappy -f -"
|
||||
];
|
||||
exec-once = [ "nm-applet --indicator" ];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
To **remove or replace** a default bind, override the whole `bind` list with
|
||||
`lib.mkForce [ … ]` (you then own the full list), or rebind the key to
|
||||
something else (last definition for a key wins in Hyprland).
|
||||
|
||||
You can also drop raw config that doesn't fit the Nix schema:
|
||||
|
||||
```nix
|
||||
{ wayland.windowManager.hyprland.extraConfig = ''
|
||||
bindl = , switch:Lid Switch, exec, hyprlock
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
### Waybar
|
||||
|
||||
For a themed bar identity, ship whole-swap assets
|
||||
(`themes/<slug>/waybar.jsonc` and `waybar.css`) — see the main README. To
|
||||
replace the bar wholesale from `home.nix`, assign `programs.waybar.settings.
|
||||
mainBar` / `programs.waybar.style` (both `mkDefault`, so a plain assignment
|
||||
wins). For a one-off tweak of a single generated key, `lib.mkForce` it.
|
||||
|
||||
## 3. Whole component — toggle it off and bring your own
|
||||
|
||||
Each desktop piece has an enable flag (all default `true`). Turn one off and
|
||||
Nomarchy contributes nothing for it, leaving the field clear for your own:
|
||||
|
||||
```nix
|
||||
# home.nix
|
||||
{
|
||||
nomarchy.hyprland.enable = false; # then write your own wayland.windowManager.hyprland
|
||||
nomarchy.waybar.enable = false;
|
||||
nomarchy.swaync.enable = false;
|
||||
nomarchy.idle.enable = false; # no hyprlock/hypridle
|
||||
}
|
||||
```
|
||||
|
||||
```nix
|
||||
# system.nix
|
||||
{
|
||||
nomarchy.system.plymouth.enable = false;
|
||||
nomarchy.system.greeter.enable = false; # bring your own login manager
|
||||
}
|
||||
```
|
||||
|
||||
See the option tables in the README for the full list.
|
||||
|
||||
## 4. Last resort: `lib.mkForce`
|
||||
|
||||
To override a value Nomarchy sets at normal priority (an appearance value, or
|
||||
a whole list), raise your definition's priority:
|
||||
|
||||
```nix
|
||||
{ lib, ... }:
|
||||
{
|
||||
# hardcode rounding against the theme (the CLI can no longer change it)
|
||||
wayland.windowManager.hyprland.settings.decoration.rounding = lib.mkForce 0;
|
||||
|
||||
# own the entire keybind list
|
||||
wayland.windowManager.hyprland.settings.bind = lib.mkForce [ "$mod, Return, exec, kitty" ];
|
||||
}
|
||||
```
|
||||
|
||||
If a plain assignment errors with *"has conflicting definition values"*, that
|
||||
value is theme-owned at normal priority — either change it via the CLI (§1) or
|
||||
`mkForce` it here.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| You want to… | Do this |
|
||||
|---|---|
|
||||
| Change gaps / colors / rounding / fonts | `nomarchy-theme-sync set …` or `apply` |
|
||||
| Change input / misc / monitor / animations / terminal chrome | plain assignment in `home.nix` |
|
||||
| Add keybinds / autostarts | add to the `bind` / `exec-once` list (concatenates) |
|
||||
| Replace all keybinds | `bind = lib.mkForce [ … ]` |
|
||||
| Hardcode an appearance value against the theme | `lib.mkForce` in `home.nix` |
|
||||
| Drop a whole component | `nomarchy.<component>.enable = false` |
|
||||
| Raw Hyprland lines | `wayland.windowManager.hyprland.extraConfig` |
|
||||
Reference in New Issue
Block a user