mirror of
https://github.com/noctalia-dev/noctalia-shell.git
synced 2026-05-11 17:08:27 +08:00
Lemmy
40 lines
2.5 KiB
Markdown
40 lines
2.5 KiB
Markdown
# Configuration
|
|
|
|
Noctalia has two configuration layers:
|
|
|
|
- Declarative user config lives in `$XDG_CONFIG_HOME/noctalia/` or `~/.config/noctalia/`.
|
|
Noctalia reads every `*.toml` file in that directory, sorted alphabetically, and deep-merges them into one config.
|
|
A single `config.toml` is the simplest setup, but splitting config into files such as `bar.toml`, `theme.toml`,
|
|
or `widgets.toml` is also supported.
|
|
- GUI-managed overrides live in `$XDG_STATE_HOME/noctalia/settings.toml` or
|
|
`~/.local/state/noctalia/settings.toml`. This file is written by Noctalia itself for settings changed through the
|
|
UI, IPC-backed controls, setup flows, and other runtime actions that need persistence.
|
|
|
|
Load order is built-in defaults first, then declarative config files, then `settings.toml`.
|
|
Because the state file is applied last, GUI overrides win over matching values in `config.toml`.
|
|
|
|
Use the declarative config directory for hand-authored, dotfile-managed configuration. Treat `settings.toml` as an
|
|
app-managed override layer: inspect or delete it when you want to understand or clear GUI changes, but do not rely on
|
|
it as the primary place for curated config. Keeping the override file outside `~/.config` also allows the GUI to save
|
|
changes when the config directory is read-only, such as on NixOS.
|
|
|
|
Both layers are watched for changes and hot-reloaded. If neither declarative config nor state overrides exist,
|
|
Noctalia falls back to built-in defaults in code.
|
|
|
|
A ready-to-use starting config with all defaults is at [example.toml](example.toml).
|
|
|
|
## Reference
|
|
|
|
| Section | Description |
|
|
|---------|-------------|
|
|
| [Bar](config/bar.md) | Bar layout, per-monitor overrides, auto-hide, widget capsule styling |
|
|
| [Widgets](config/widgets.md) | Widget definitions and all built-in widget types |
|
|
| [Scripted Widgets](config/scripted-widgets.md) | Custom Luau-driven bar widgets |
|
|
| [Dock](config/dock.md) | Application dock, pinned apps, auto-hide, IPC |
|
|
| [Desktop Widgets](config/desktop-widgets.md) | Desktop overlay widgets, edit mode, state file format |
|
|
| [Wallpaper](config/wallpaper.md) | Wallpaper picker, overview backdrop, automation |
|
|
| [Theme](config/theme.md) | Color schemes, modes, wallpaper-derived palettes |
|
|
| [Theming Templates](config/theming-templates.md) | App theme template generation and export paths |
|
|
| [Services](config/services.md) | Audio, sound cues, brightness, night light, weather, idle, notifications |
|
|
| [Shell](config/shell.md) | Global UI settings, OSD, keybinds, hooks |
|