docs: add OPTIONS.md reference, link from README
Catalogues every nomarchy.{system,hardware,…} and nomarchy.* (home) option
so downstream flake users can see what's available without grepping
options.nix. Linked from the Configuration & Usage section of README.md.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Bernardo Magri
281
docs/OPTIONS.md
Normal file
281
docs/OPTIONS.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# Nomarchy Options Reference
|
||||
|
||||
Every option Nomarchy exposes for downstream flakes. Paths under `nomarchy.system.*` are NixOS options (set in `system.nix`); paths under `nomarchy.*` (no `system` segment) are Home Manager options (set in `home.nix`). `nomarchy.hardware.*` is NixOS.
|
||||
|
||||
The installer-generated configuration writes a few of these for you (timezone, formFactor, hardware vendor flags, keymap, locale). Anything not listed there is opt-in — set it yourself.
|
||||
|
||||
To see the live default for any option:
|
||||
|
||||
```bash
|
||||
nix eval .#nixosConfigurations.<host>.config.nomarchy.system.<path>
|
||||
nix eval .#homeConfigurations.<user>.config.nomarchy.<path>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## NixOS options (`system.nix`)
|
||||
|
||||
### `nomarchy.system.dns`
|
||||
|
||||
DNS provider. One of `"DHCP"` (default), `"Cloudflare"`, `"Google"`, `"Custom"`. With `"Custom"`, set `nomarchy.system.customDns` to a list of nameservers. Anything other than `"DHCP"` also enables `services.resolved` with DNSSEC and DNS-over-TLS.
|
||||
|
||||
Defined in `core/system/options.nix`; wired in `core/system/network.nix`.
|
||||
|
||||
### `nomarchy.system.customDns`
|
||||
|
||||
`listOf str`, default `[]`. Nameservers used when `dns = "Custom"`.
|
||||
|
||||
### `nomarchy.system.wifi.powersave`
|
||||
|
||||
`bool`, default `true`. Sets `networking.networkmanager.wifi.powersave`. Turn off if you see drops on idle Wi-Fi.
|
||||
|
||||
### `nomarchy.system.timezone`
|
||||
|
||||
`str`, default `"UTC"`. The installer writes `time.timeZone` directly, so this option is informational unless you wire it into your own modules.
|
||||
|
||||
### `nomarchy.system.formFactor`
|
||||
|
||||
`enum [ "laptop" "desktop" ]`, default `"laptop"`. Drives UI affordances and (eventually) lid handling / TLP. The installer auto-detects via `/sys/class/power_supply/BAT*`. The default is `"laptop"` because the battery widget renders empty when no battery is present — safe on a desktop, useful on a laptop.
|
||||
|
||||
Wired in `features/desktop/waybar/default.nix` (filters the battery widget out on desktop) and `features/scripts/battery-monitor.nix` (skips the timer on desktop).
|
||||
|
||||
### `nomarchy.system.theme`
|
||||
|
||||
`str`, default `"summer-night"`. Theme name. Mirror of the home-side `nomarchy.theme`. Set both if you also want NixOS-side modules (e.g. SDDM theming) to follow.
|
||||
|
||||
### `nomarchy.system.features.fingerprint`
|
||||
|
||||
`bool`, default `false`. Enables `services.fprintd.enable`.
|
||||
|
||||
### `nomarchy.system.features.fido2`
|
||||
|
||||
`bool`, default `false`. Enables `security.pam.u2f` (sufficient, with cue).
|
||||
|
||||
### `nomarchy.system.features.hybridGPU`
|
||||
|
||||
`bool`, default `false`. Enables `services.supergfxd.enable` for laptops with switchable GPUs.
|
||||
|
||||
### `nomarchy.system.snapper.enable`
|
||||
|
||||
`bool`, default `false`. BTRFS timeline snapshots of `/`. Auto-disables when `/` isn't BTRFS. Includes a `nixos-rebuild-snap` wrapper that takes a "Pre-rebuild" snapshot before each switch.
|
||||
|
||||
### `nomarchy.system.hibernation.enable`
|
||||
|
||||
`bool`, default `false`. Suspend-then-hibernate on lid close, idle, and power button. Requires a disk swap device or swapfile sized to at least RAM — zRAM alone is not enough.
|
||||
|
||||
### `nomarchy.system.hibernation.idleMinutes`
|
||||
|
||||
`int`, default `30`. Idle minutes before suspend-then-hibernate fires.
|
||||
|
||||
### `nomarchy.system.containers.enable`
|
||||
|
||||
`bool`, default `false`. Rootless Podman with Docker compatibility (`docker` → `podman`), plus `podman-compose`, `podman-tui`, and `dive`.
|
||||
|
||||
### `nomarchy.system.virtualization.libvirt.enable`
|
||||
|
||||
`bool`, default `false`. libvirt daemon, virt-manager, and OVMF. Add your user to the `libvirtd` group.
|
||||
|
||||
### `nomarchy.system.keyring.enable`
|
||||
|
||||
`bool`, default `true`. Auto-unlock GNOME Keyring at login and route SSH keys through `gcr-ssh-agent`. On by default — near-universal QoL improvement.
|
||||
|
||||
### `nomarchy.system.inputMethod.enable`
|
||||
|
||||
`bool`, default `false`. fcitx5 input method for CJK / IME. Wires NixOS's `i18n.inputMethod` and autostarts `fcitx5-daemon`.
|
||||
|
||||
### `nomarchy.system.voxtype.enable`
|
||||
|
||||
`bool`, default `false`. voxtype voice-typing integration. voxtype isn't packaged in nixpkgs — when you enable this, install voxtype yourself (e.g. `home.packages = [ (pkgs.callPackage … {}) ]`). With this off the `SUPER+CTRL+X` keybinding and waybar widget are no-ops.
|
||||
|
||||
### `nomarchy.hardware.isXPS`
|
||||
|
||||
`bool`, default `false`. Dell XPS fixes — haptic touchpad service and PCI/I²C power-control udev rules.
|
||||
|
||||
### `nomarchy.hardware.isT2Mac`
|
||||
|
||||
`bool`, default `false`. Apple T2 MacBook fixes — IOMMU kernel params, `apple-bce` module, brcmfmac feature mask.
|
||||
|
||||
### `nomarchy.hardware.isFramework`
|
||||
|
||||
`bool`, default `false`. Framework laptop QMK HID udev rule.
|
||||
|
||||
### `nomarchy.hardware.hasIPU7Camera`
|
||||
|
||||
`bool`, default `false`. Intel IPU7 camera support (kernel modules + firmware).
|
||||
|
||||
### `impermanence.enable`
|
||||
|
||||
`bool`, default `false`. Erase Your Darlings root wipe on boot. Defined in `core/system/impermanence.nix`. The installer writes the flag based on the impermanence prompt.
|
||||
|
||||
---
|
||||
|
||||
## Home Manager options (`home.nix`)
|
||||
|
||||
### `nomarchy.theme`
|
||||
|
||||
`str`, default `"summer-night"`. Active theme name. Available themes are the directories under `themes/palettes/`.
|
||||
|
||||
### `nomarchy.formFactor`
|
||||
|
||||
`enum [ "laptop" "desktop" ]`, default `"laptop"`. Mirror of `nomarchy.system.formFactor`. Filters laptop-only widgets out of waybar (battery) when set to `"desktop"`. The installer writes both system and home values together.
|
||||
|
||||
### `nomarchy.wallpaper`
|
||||
|
||||
`str`, default `""`. Absolute path to a wallpaper override. Empty string means "use the active theme's default wallpaper".
|
||||
|
||||
### `nomarchy.toggles.suspend`
|
||||
|
||||
`bool`, default `true`. Whether suspend appears in the system menu.
|
||||
|
||||
### `nomarchy.toggles.screensaver`
|
||||
|
||||
`bool`, default `true`. Whether the screensaver is enabled.
|
||||
|
||||
### `nomarchy.toggles.idle`
|
||||
|
||||
`bool`, default `true`. Whether the idle lock is enabled (hypridle).
|
||||
|
||||
### `nomarchy.toggles.nightlight`
|
||||
|
||||
`bool`, default `false`. Enables hyprsunset.
|
||||
|
||||
### `nomarchy.toggles.waybar`
|
||||
|
||||
`bool`, default `true`. Whether the top bar is deployed at all.
|
||||
|
||||
### `nomarchy.toggles.skipVsCodeTheme`
|
||||
|
||||
`bool`, default `false`. Skip theme overrides in VSCode — useful if you manage VSCode themes yourself.
|
||||
|
||||
### `nomarchy.nightlightTemperature`
|
||||
|
||||
`int`, default `4000`. Nightlight color temperature (Kelvin).
|
||||
|
||||
### `nomarchy.hyprland.gaps_in`
|
||||
|
||||
`int`, default `5`. Inner gaps.
|
||||
|
||||
### `nomarchy.hyprland.gaps_out`
|
||||
|
||||
`int`, default `10`. Outer gaps.
|
||||
|
||||
### `nomarchy.hyprland.border_size`
|
||||
|
||||
`int`, default `2`. Window border width.
|
||||
|
||||
### `nomarchy.fonts.monospace`
|
||||
|
||||
`str`, default `"JetBrainsMono Nerd Font"`. Used by terminals, VSCode, etc.
|
||||
|
||||
### `nomarchy.iconsTheme`
|
||||
|
||||
`str`, default `"Yaru-blue"`. GTK/Qt icon theme name.
|
||||
|
||||
### `nomarchy.isLightMode`
|
||||
|
||||
`bool`, default `false`. Whether the active theme is a light theme. Affects nightlight defaults and a few app theme decisions.
|
||||
|
||||
### `nomarchy.cursor.name`
|
||||
|
||||
`str`, default `"Bibata-Modern-Ice"`. Cursor theme name.
|
||||
|
||||
### `nomarchy.cursor.package`
|
||||
|
||||
`package`, default `pkgs.bibata-cursors`. Package providing the cursor theme. Override both `name` and `package` together if you switch themes.
|
||||
|
||||
### `nomarchy.configOverrides`
|
||||
|
||||
`nullOr path`, default `null`. Path to a directory containing config overrides. See "Overrides" below.
|
||||
|
||||
### `nomarchy.behavior.hyprland.bindings`
|
||||
|
||||
`bool`, default `true`. Deploy the default Hyprland keybindings. Set to `false` if you want to write `bindings.conf` from scratch.
|
||||
|
||||
### `nomarchy.behavior.hyprland.input`
|
||||
|
||||
`bool`, default `true`. Deploy default input settings (kb_layout, mouse accel, etc).
|
||||
|
||||
### `nomarchy.behavior.hyprland.windowRules`
|
||||
|
||||
`bool`, default `true`. Deploy default window rules.
|
||||
|
||||
### `nomarchy.behavior.hyprland.autostart`
|
||||
|
||||
`bool`, default `true`. Deploy the default `autostart.conf` (hypridle, mako, swayosd, nm-applet, etc).
|
||||
|
||||
### `nomarchy.apps.opencode.enable`
|
||||
|
||||
`bool`, default `false`. opencode AI coding CLI integration. Deploys `~/.config/opencode/opencode.json`. The `opencode` package itself is **not** installed by Nomarchy — add it to your `home.packages`.
|
||||
|
||||
### `nomarchy.vscode.devExtensions`
|
||||
|
||||
`bool`, default `false`. Install Nomarchy's curated VSCode extension pack (Nix, language servers, theme variants).
|
||||
|
||||
### `nomarchy.themeLoader.enable`
|
||||
|
||||
`bool`, default `true`. Auto-load theme-specific app configs (btop, waybar, mako, kitty, alacritty) from the active theme. Disable if you want to provide your own.
|
||||
|
||||
### `nomarchy.themeLoader.apps.{btop,waybar,mako,kitty,alacritty}`
|
||||
|
||||
`bool`, default `true` each. Per-app toggles for the theme loader — pick which apps follow the active theme.
|
||||
|
||||
### `nomarchy.overrides.enable`
|
||||
|
||||
`bool`, default `true`. Enable file-based overrides loaded from `~/.config/nomarchy/overrides/`. With this on, Nomarchy looks for matching files in that directory and substitutes them for the bundled defaults.
|
||||
|
||||
### `nomarchy.overrides.paths`
|
||||
|
||||
`attrsOf path`, default `{}`. Override paths discovered at build time. Populated by the override system — you don't normally set this directly.
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Minimal `system.nix` for a desktop with Cloudflare DNS, Snapper, and rootless Podman
|
||||
|
||||
```nix
|
||||
{
|
||||
nomarchy.system = {
|
||||
dns = "Cloudflare";
|
||||
formFactor = "desktop";
|
||||
snapper.enable = true;
|
||||
containers.enable = true;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Minimal `home.nix` for a Tokyo-night user with custom gaps and opencode
|
||||
|
||||
```nix
|
||||
{
|
||||
nomarchy = {
|
||||
theme = "tokyo-night";
|
||||
hyprland.gaps_in = 8;
|
||||
hyprland.gaps_out = 16;
|
||||
apps.opencode.enable = true;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Disable Nomarchy's default Hyprland keybindings to ship your own
|
||||
|
||||
```nix
|
||||
{
|
||||
nomarchy.behavior.hyprland.bindings = false;
|
||||
}
|
||||
```
|
||||
|
||||
Then put your own `bindings.conf` at `~/.config/nomarchy/overrides/hypr/bindings.conf` (with `nomarchy.overrides.enable = true;`, which is the default).
|
||||
|
||||
---
|
||||
|
||||
## Where these are defined
|
||||
|
||||
- `core/system/options.nix` — most `nomarchy.system.*` options
|
||||
- `core/system/hardware.nix` — `nomarchy.hardware.*`
|
||||
- `core/system/impermanence.nix` — `impermanence.enable`
|
||||
- `core/home/options.nix` — most home-side `nomarchy.*` options
|
||||
- `core/home/behavior.nix` — `nomarchy.behavior.*`
|
||||
- `core/home/overrides.nix` — `nomarchy.overrides.*`
|
||||
- `themes/engine/loader.nix` — `nomarchy.themeLoader.*`
|
||||
- `features/apps/vscode.nix` — `nomarchy.vscode.*`
|
||||
Reference in New Issue
Block a user