docs: add further documentation about theme file

README.md

@@ -39,6 +39,7 @@ By deliberately making some decisions differently, eza attempts to be a more fea
 - Several security fixes.
 - Support for `bright` terminal colours.
 - Many smaller bug fixes/changes!
+- Configuration `theme.yml` file for customization of colors and icons.
 
 ...and like, so much more that it became exhausting to update this all the time.
 Like seriously, we have a lot of good stuff.
@@ -161,11 +162,30 @@ Some of the options accept parameters:
 - Valid time fields are **modified**, **changed**, **accessed**, and **created**.
 - Valid time styles are **default**, **iso**, **long-iso**, **full-iso**, and **relative**.
 
-</details>
+
 
 See the `man` pages for further documentation of usage. They are available
 - online [in the repo](https://github.com/eza-community/eza/tree/main/man)
 - in your terminal via `man eza`, as of version [`[0.18.13] - 2024-04-25`](https://github.com/eza-community/eza/blob/main/CHANGELOG.md#01813---2024-04-25)
+</details>
+
+
+## Custom Themes
+<details>
+<summary>Click to expand</summary>
+
+**Eza** has recently added support for a `theme.yml` file, where you can specify all of the existing theme-ing options
+available for the `LS_COLORS` and `EXA_COLORS` environment variables, as well as the option to specify different icons
+for different file types and extensions. Any existing environment variables set will continue to work and will take
+precedence for backwards compatibility.
+
+An example theme file is available in `docs/theme.yml`, and needs to either be placed in a directory specified by the 
+environment variable `EZA_CONFIG_DIR`, or will looked for by default in `$XDG_CONFIG_HOME/eza`.
+
+Full details are available on the [man page](https://github.com/eza-community/eza/tree/main/man/eza_colors-explanation.5.md) and an example theme file is included [here](https://github.com/eza-community/eza/tree/main/docs/theme.yml)
+
+</details>
+
 
 # Hacking on eza
 

themes/theme.yml → docs/theme.yml

@@ -32,20 +32,16 @@ perms:
     foreground: Red
   other_execute:
     foreground: Green
+
 filenames:
   # Just change the icon glyph
   Cargo.toml: {icon: {glyph: 🦀}}
   Cargo.lock: {icon: {glyph: 🦀}}
+
 extensions:
   # Change the filename color and icon
+  # NOTE: not all unicode glyphs support color changes
   rs: {filename: {foreground: Red}, icon: {glyph: 🦀}}
+
   # Change the icon glyph and color
   nix: {icon: {glyph: ❄, style: {foreground: White}}}
-icon_overrides:
-icons:
-  filenames:
-    Cargo.toml: {icon: 🦀}
-    Cargo.lock: {icon: 🦀}
-  extensions:
-    rs: {icon: 🦀}
-    nix: {icon: ❄, style: {foreground: White}}

man/eza_colors-explanation.5.md

@@ -45,6 +45,187 @@ in the same directory as one of its source files: styles.css will count as compi
 - Source files (cpp, js, java) are bright yellow.
 
 
+## Theme Configuration file
+
+Now you can specify these options and more in a `theme.yml` file with convenient syntax for defining your styles.
+
+Set `EZA_CONFIG_DIR` to specify which directory you would like eza to look for your `theme.yml` file,
+otherwise eza will look for `$XDG_CONFIG_HOME/eza/theme.yml`.
+
+
+These are the available options:
+
+LIST OF THEME OPTIONS
+=====================
+
+```yaml
+filekinds:
+  normal
+  directory
+  symlink
+  pipe
+  block_device
+  char_device
+  socket
+  special
+  executable
+  mount_point
+
+perms:
+  user_read
+  user_write
+  user_executable_file
+  user_execute_other
+  group_read
+  group_write
+  group_execute
+  other_read
+  other_write
+  other_execute
+  special_user_file
+  special_other
+  attribute
+
+size:
+  major
+  minor
+  number_byte
+  number_kilo
+  number_mega
+  number_giga
+  number_huge
+  unit_byte
+  unit_kilo
+  unit_mega
+  unit_giga
+  unit_huge
+
+users:
+  user_you
+  user_root
+  user_other
+  group_yours
+  group_other
+  group_root
+
+links:
+  normal
+  multi_link_file
+
+git:
+  new
+  modified
+  deleted
+  renamed
+  ignored
+  conflicted
+
+git_repo:
+  branch_main
+  branch_other
+  git_clean
+  git_dirty
+
+security_context:
+  none:
+  selinux:
+    colon
+    user
+    role
+    typ
+    range
+
+file_type:
+  image
+  video
+  music
+  crypto
+  document
+  compressed
+  temp
+  compiled
+  build
+  source
+
+punctuation:
+
+date:
+
+inode:
+
+blocks:
+
+header:
+
+octal:
+
+flags:
+
+control_char:
+
+broken_symlink:
+
+broken_path_overlay:
+
+```
+
+Each of those fields/sub fields can have the following styling properties defined beneath it
+
+```yaml
+    foreground: Blue
+    background: null
+    is_bold: false
+    is_dimmed: false
+    is_italic: false
+    is_underline: false
+    is_blink: false
+    is_reverse: false
+    is_hidden: false
+    is_strikethrough: true
+    prefix_with_reset: false
+```
+
+Example:
+
+```yaml
+
+file_type:
+  image:
+    foreground: Blue
+    is_italic: true
+date:
+  foreground: White
+
+security_context:
+  selinux:
+    role:
+      is_hidden: true
+```
+
+Icons can now be customized as well in the `filenames` and `extensions` fields
+
+```yaml
+
+filenames:
+  # Just change the icon glyph
+  Cargo.toml: {icon: {glyph: 🦀}}
+  Cargo.lock: {icon: {glyph: 🦀}}
+
+extensions:
+  rs: {  filename: {foreground: Red}, icon: {glyph: 🦀}}
+
+```
+
+**NOTES:** 
+
+Not all glyphs support changing colors.
+
+If your theme is not working properly, double check the syntax in the config file, as
+a syntax issue can cause multiple properties to not be applied.
+
+You must name the file `theme.yml`, no matter the directory you specify.
+
+
 ## See also
 
 - [eza.1.md](eza.1.md)