Clarify creating a custom module (#164)

* Clarify creating a custom module

* Fix path

Co-authored-by: Hamothy <58985301+sgoudham@users.noreply.github.com>

* Fix formatting and mention required plugins

* docs: indentation & small tweaks

---------

Co-authored-by: Hamothy <58985301+sgoudham@users.noreply.github.com>
Co-authored-by: sgoudham <sgoudham@gmail.com>

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.
+For further details, see the documentation in [custom/README.md](custom/README.md)
 
 Any file added to the custom folder will be preserved when updating catppuccin.
 

custom/README.md

@@ -1,43 +1,72 @@
-# User defined modules
+# User Defined Modules
 
-## 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 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.
 
-This folder is used to store user defined modules.
+## Creating A New Module
-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.
 
-## Create a new module
+> [!NOTE]
+> Changes will only be applied after reloading your Tmux configuration by executing `tmux source-file ~/.tmux.conf`.
 
-Use the [Module template](#module-template) (or example.sh) as a starting point when creating a new module.
+You can create a custom module by following the steps outlined below. This can be something you create entirely by yourself or integrating an existing Tmux plugin.
-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> ..."
 
-```
+1. Create a new file in `~/.tmux/plugins/tmux/custom/<module_name>.sh` to store the custom module.
+    - The file **must** end in `.sh`
+    - The file **does not** need to be set as executable.
 
-## Module template
+2. Copy the following template to this new file. Make sure to replace every instance of `<module_name>` by the name you chose as filename.
-```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>")"
 
-  local module=$( build_status_module "$index" "$icon" "$color" "$text" )
+    ```bash
+    # If this module depends on an external Tmux plugin, say so in a comment.
+    # E.g.: Requires https://github.com/aaronpowell/tmux-weather
+
+    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" )"
+
+      module=$( build_status_module "$index" "$icon" "$color" "$text" )
 
       echo "$module"
-}
+    }
+    ```
+
+3. Add the custom module to the list of modules in `.tmux.conf`
+
+    ```bash
+    set -g @catppuccin_status_modules_right "... <module_name> ..."
+    ```
+
+## Customization
+
+Change the icon to one from [Nerd Fonts](https://www.nerdfonts.com/cheat-sheet).
+
+Change the color to one of the [official colors](../catppuccin-macchiato.tmuxtheme), for instance `"$thm_cyan"`, 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, for instance by having a Bash script `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>
 ```
 
-## Configure custom modules path
+To configure a custom path for your modules, set this option:
 
-You can configure a custom path for your modules by setting the `@catppuccin_custom_plugin_dir` option.
+```tmux
-```sh 
 set -g @catppuccin_custom_plugin_dir "<path>"
 ```
-
-To use the output of a command, use e.g. `local text="$(get_tmux_option "@catppuccin_test_text" "#(date +%T)")"`.
-
-To use the output of a script, use e.g. `local text="$(get_tmux_option "@catppuccin_test_text" "#($HOME/my_script.sh)")"`.

custom/example.sh

@@ -1,10 +1,16 @@
-show_example() {
+# If this module depends on an external Tmux plugin, say so in a comment.
-  local index=$1
+# E.g.: Requires https://github.com/aaronpowell/tmux-weather
-  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!")"
 
-  local module=$( build_status_module "$index" "$icon" "$color" "$text" )
+show_test() { # 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_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"
 }
+