v5-theming-app-theming.md
Noctalia can render the resolved theme colors into external app config files whenever the palette changes. This lets terminals, editors, browsers, launchers, and other apps follow the same colors as the shell.
To rerender enabled templates for the current palette without changing the theme, use Media & UI → Theme.
Section titled “Built-in Templates”
Built-in templates ship with Noctalia. Enable the built-in catalog, then opt in to the template IDs you want:
[theme.templates]enable_builtin_templates = truebuiltin_ids = [] # opt-in; run: noctalia theme --list-templates
builtin_ids selects which shipped templates run. An empty array means no built-in templates are applied.
List available built-in and configured template IDs:
Terminal window
noctalia theme --list-templates
Section titled “Community Templates”
Community templates are fetched from https://api.noctalia.dev/templates and cached locally:
[theme.templates]enable_community_templates = truecommunity_ids = [] # opt-in; fetched from api.noctalia.dev/templates
community_ids selects which community templates run. Metadata and files are cached in ~/.cache/noctalia/community-templates/ (honoring XDG_CACHE_HOME).
Cached community template files are treated as editable local copies. Sync updates files only while their content still matches the last Noctalia-written md5; local edits are preserved until you delete the edited cached file.
Community template discovery and updates require network access unless the selected template is already cached. shell.offline_mode prevents outgoing HTTP requests, including community template requests.
Section titled “User Templates”
User templates are declared directly in Noctalia config:
[theme.templates.user.my_app]input_path = "$XDG_CONFIG_HOME/noctalia/templates/my-app.css"output_path = "$XDG_CONFIG_HOME/my-app/theme.css"post_hook = "my-app --reload-theme"
Defining [theme.templates.user.<id>] enables that user template. Set enabled = false on an entry to keep it available but inactive.
Relative paths resolve from the Noctalia config directory. A leading $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_STATE_HOME, or $XDG_CACHE_HOME token is expanded using the XDG base directory defaults when the matching environment variable is not set.
User template entries support the same fields documented in Template Entries, including input_path_modes, output_path_dynamic, colors_to_compare, compare_to, pre_hook, post_hook, and index.
Section titled “Config Location”
Put dotfile-managed templates in ~/.config/noctalia/*.toml:
~/.config/noctalia/templates.toml
[theme.templates]enable_builtin_templates = trueenable_community_templates = truebuiltin_ids = []community_ids = []
[theme.templates.user.my_app]input_path = "$XDG_CONFIG_HOME/noctalia/templates/my-app.css"output_path = "$XDG_CONFIG_HOME/my-app/theme.css"
The same tables are valid in settings.toml because it is the final config overlay, but that file is managed by the GUI and runtime actions. Use ~/.config/noctalia/ for templates you want to keep in dotfiles.
Section titled “Template Reference”
For template syntax, color tokens, filters, hooks, dynamic output paths, and CLI rendering, see the Template Reference.