Clarify creating a custom module

README.md

@@ -431,7 +431,7 @@ set -g @catppuccin_status_modules_right "... uptime ..."
 
 It is possible to add a new custom module or overwrite any of the existing modules.
 
-Look into custom/README.md for more details.
+Look into [custom/README.md](https://github.com/catppuccin/tmux/blob/main/README.md) for more details.
 
 Any file added to the custom folder will be preserved when updating catppuccin.
 

custom/README.md

@@ -1,43 +1,70 @@
 # User defined modules
 
-## Description 
+## Description
 
 This folder is used to store user defined modules.
 You can use this folder to add a new module or override any existing module.
-To override an existing module, make sure you use the same name for your module as the module you want to override.
-You can also override the window module for current and default window.
+To override an existing module, make sure that you use the same name for your module as the module you want to override.
+You can also override the window module for the current and default window.
 
 ## Create a new module
 
-Use the [Module template](#module-template) (or example.sh) as a starting point when creating a new module.
-Save the new module under this folder using the module name as the file name and .sh as the extension.
-Update the status module list with your module.
-```sh
-set -g @catppuccin_status_modules_right "... <module_name> ..."
+You can create a custom module by following these steps.
+Note that changes will only take effect after reloading your Tmux configuration by executing `tmux source-file ~/.tmux.conf`.
 
-```
+### New file
+
+Create a new file in `~/.tmux/plugins/tmux/custom/<module_name>.sh`, to store the custom module. The extension has to be `.sh`. Making this file executable is not necessary.
+
+### File content
+
+Copy the following template to that file. Make sure to replace every instance of `<module_name>` by the name you chose as filename.
 
-## Module template
 ```sh
-show_<module_name>() { # save this module in a file with the name <module_name>.sh
-  local index=$1 # this variable is used by the module loader in order to know the position of this module 
-  local icon="$(get_tmux_option "@catppuccin_<module_name>_icon" "<Use an icon from [nerdfonts](https://www.nerdfonts.com/cheat-sheet)>")"
-  local color="$(get_tmux_option "@catppuccin_<module_name>_color" "<Use one of the default theme colors (ex: $thm_orange), or provide a color code (ex: #ef9f76)>")"
-  local text="$(get_tmux_option "@catppuccin_<module_name>_text" "<Provide the text that you want to be displayed>")"
+show_<module_name>() { # This function name must match the module name!
+  local index icon color text module
+
+  index=$1 # This variable is used internally by the module loader in order to know the position of this module 
+  icon="$(  get_tmux_option "@catppuccin_<module_name>_icon"  ""           )"
+  color="$( get_tmux_option "@catppuccin_<module_name>_color" "$thm_orange" )"
+  text="$(  get_tmux_option "@catppuccin_<module_name>_text"  "hello world" )"
 
-  local module=$( build_status_module "$index" "$icon" "$color" "$text" )
+  module=$( build_status_module "$index" "$icon" "$color" "$text" )
 
   echo "$module"
 }
 ```
 
-## Configure custom modules path
+### Status module list
 
-You can configure a custom path for your modules by setting the `@catppuccin_custom_plugin_dir` option.
-```sh 
-set -g @catppuccin_custom_plugin_dir "<path>"
+Add the custom module to the list of modules in `.tmux.conf`
+
+```tmux
+set -g @catppuccin_status_modules_right "... <module_name> ..."
 ```
 
-To use the output of a command, use e.g. `local text="$(get_tmux_option "@catppuccin_test_text" "#(date +%T)")"`.
+### Customization
 
-To use the output of a script, use e.g. `local text="$(get_tmux_option "@catppuccin_test_text" "#($HOME/my_script.sh)")"`.
+Change the icon to one from [Nerd Fonts](https://www.nerdfonts.com/cheat-sheet).
+Change the color to one of the [official colors](https://github.com/catppuccin/tmux/blob/main/catppuccin-macchiato.tmuxtheme), for instance `"$thm_orange"`, or to a hexadecimal color like `"#00ff00"`.
+
+The text to display can either be:
+
+- A static text, e.g. `"hello world"`.
+- The output of a command, e.g. `"#( date +%T )"`.
+- The output of a script, e.g. `"#( $HOME/my_script.sh )"` . Any script will do, e.g. a Bash or Python script that prints some text, but ensure that it is executable `chmod u+x my_script.sh`.
+- An existing Tmux plugin, e.g. `" #{forecast} "` for the [Tmux Weather plugin](https://github.com/aaronpowell/tmux-weather).
+
+Note that the icon and the color can be generated dynamically as well, by having a Bash script e.g. `echo` a hexadecimal color.
+
+To modify how often the modules are updated, add the following to `.tmux.conf`:
+
+```tmux
+set -g status-interval <number of seconds>
+```
+
+To configure a custom path for your modules, set this option:
+
+```tmux
+set -g @catppuccin_custom_plugin_dir "<path>"
+```

custom/example.sh

@@ -1,10 +1,13 @@
-show_example() {
-  local index=$1
-  local icon="$(get_tmux_option "@catppuccin_test_icon" "󰙨")"
-  local color="$(get_tmux_option "@catppuccin_test_color" "$thm_blue")"
-  local text="$(get_tmux_option "@catppuccin_test_text" "It works!")"
+show_test() { # This function name must match the module name!
+  local index icon color text module
 
-  local module=$( build_status_module "$index" "$icon" "$color" "$text" )
+  index=$1 # This variable is used internally by the module loader in order to know the position of this module
+  icon="$(  get_tmux_option "@catppuccin_test_icon"  ""           )"
+  color="$( get_tmux_option "@catppuccin_test_color" "$thm_orange" )"
+  text="$(  get_tmux_option "@catppuccin_test_text"  "hello world" )"
+
+  module=$( build_status_module "$index" "$icon" "$color" "$text" )
 
   echo "$module"
 }
+