From 6bb09e77039bfe4efd67459bfd60d94403d8291e Mon Sep 17 00:00:00 2001
From: AteebXYZ <130910481+AteebXYZ@users.noreply.github.com>
Date: Fri, 20 Mar 2026 12:56:12 +0300
Subject: [PATCH] readme: document user templates (#99)

* document user_templates in README

* move user_template documentation to Usage

* format

---------

Co-authored-by: 2 * r + 2 * t <61896496+soramanew@users.noreply.github.com>
---
 README.md | 51 ++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 36 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 7239cc3..ad3af24 100644
--- a/README.md
+++ b/README.md
@@ -4,40 +4,43 @@ The main control script for the Caelestia dotfiles.
 
 <details><summary id="dependencies">External dependencies</summary>
 
--   [`libnotfy`](https://gitlab.gnome.org/GNOME/libnotify) - sending notifications
--   [`swappy`](https://github.com/jtheoof/swappy) - screenshot editor
--   [`grim`](https://gitlab.freedesktop.org/emersion/grim) - taking screenshots
--   [`dart-sass`](https://github.com/sass/dart-sass) - discord theming
--   [`app2unit`](https://github.com/Vladimir-csp/app2unit) - launching apps
--   [`wl-clipboard`](https://github.com/bugaevc/wl-clipboard) - copying to clipboard
--   [`slurp`](https://github.com/emersion/slurp) - selecting an area
--   [`gpu-screen-recorder`](https://git.dec05eba.com/gpu-screen-recorder/about) - screen recording
--   `glib2` - closing notifications
--   [`cliphist`](https://github.com/sentriz/cliphist) - clipboard history
--   [`fuzzel`](https://codeberg.org/dnkl/fuzzel) - clipboard history/emoji picker
+- [`libnotfy`](https://gitlab.gnome.org/GNOME/libnotify) - sending notifications
+- [`swappy`](https://github.com/jtheoof/swappy) - screenshot editor
+- [`grim`](https://gitlab.freedesktop.org/emersion/grim) - taking screenshots
+- [`dart-sass`](https://github.com/sass/dart-sass) - discord theming
+- [`app2unit`](https://github.com/Vladimir-csp/app2unit) - launching apps
+- [`wl-clipboard`](https://github.com/bugaevc/wl-clipboard) - copying to clipboard
+- [`slurp`](https://github.com/emersion/slurp) - selecting an area
+- [`gpu-screen-recorder`](https://git.dec05eba.com/gpu-screen-recorder/about) - screen recording
+- `glib2` - closing notifications
+- [`cliphist`](https://github.com/sentriz/cliphist) - clipboard history
+- [`fuzzel`](https://codeberg.org/dnkl/fuzzel) - clipboard history/emoji picker
 
 </details>
 
 <details><summary id="optional-dependencies">Optional dependencies</summary>
 
--   [`papirus-folders`](https://github.com/PapirusDevelopmentTeam/papirus-folders) - automatic folder icon color syncing with theme
+- [`papirus-folders`](https://github.com/PapirusDevelopmentTeam/papirus-folders) - automatic folder icon color syncing with theme
 
 > [!NOTE]
 > For automatic Papirus folder icon color syncing, `papirus-folders` needs to be able to run with `sudo` without a password prompt.
-> 
+>
 > **Recommended** - Create a sudoers file:
+>
 > ```fish
 > # Fish shell
 > echo "$USER ALL=(ALL) NOPASSWD: "(which papirus-folders) | sudo tee /etc/sudoers.d/papirus-folders
 > sudo chmod 440 /etc/sudoers.d/papirus-folders
 > ```
+>
 > ```sh
 > # Bash/other shells
 > echo "$USER ALL=(ALL) NOPASSWD: $(which papirus-folders)" | sudo tee /etc/sudoers.d/papirus-folders
 > sudo chmod 440 /etc/sudoers.d/papirus-folders
 > ```
-> 
+>
 > **Alternatively** - Edit the main sudoers file by running `sudo visudo` and adding at the end:
+>
 > ```
 > your_username ALL=(ALL) NOPASSWD: /usr/bin/papirus-folders
 > ```
@@ -148,6 +151,24 @@ subcommands:
     resizer      window resizer daemon
 ```
 
+### User Templates
+
+Custom user templates can be defined in `~/.config/caelestia/templates/`.
+
+#### Template syntax
+
+`{{ <color>.<format> }}`
+
+- `<color>` is a theme color role derived from the Material You color system (e.g. `primary`, `secondary`, `background`)
+- `<format>` is the output format: `hex` or `rgb`
+
+#### Examples
+
+- `{{ primary.hex }}` outputs `3f4ba2`
+- `{{ primary.rgb }}` outputs `rgb(193, 132, 207)`
+
+Output files are written to `~/.local/state/caelestia/theme/`. You can symlink them to your desired locations.
+
 ## Configuring
 
 All configuration options are in `~/.config/caelestia/cli.json`.
@@ -160,7 +181,7 @@ All configuration options are in `~/.config/caelestia/cli.json`.
         "extraArgs": []
     },
     "wallpaper": {
-        "postHook": "echo $WALLPAPER_PATH"  
+        "postHook": "echo $WALLPAPER_PATH"
     },
     "theme": {
         "enableTerm": true,