diff --git a/README.md b/README.md index 29ef238f..f14b54f9 100644 --- a/README.md +++ b/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. diff --git a/custom/README.md b/custom/README.md index b4a11cb8..65f66bf3 100644 --- a/custom/README.md +++ b/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. -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. +## Creating A New Module -## 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. -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 "... ..." +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. -``` +1. Create a new file in `~/.tmux/plugins/tmux/custom/.sh` to store the custom module. + - The file **must** end in `.sh` + - The file **does not** need to be set as executable. -## Module template -```sh -show_() { # save this module in a file with the 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__icon" "")" - local color="$(get_tmux_option "@catppuccin__color" "")" - local text="$(get_tmux_option "@catppuccin__text" "")" +2. Copy the following template to this new file. Make sure to replace every instance of `` by the name you chose as filename. - 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 - echo "$module" -} -``` + show_() { # This function name must match the module name! + local index icon color text module -## Configure custom modules path + index=$1 # This variable is used internally by the module loader in order to know the position of this module -You can configure a custom path for your modules by setting the `@catppuccin_custom_plugin_dir` option. -```sh -set -g @catppuccin_custom_plugin_dir "" + icon="$( get_tmux_option "@catppuccin__icon" "" )" + color="$( get_tmux_option "@catppuccin__color" "$thm_orange" )" + text="$( get_tmux_option "@catppuccin__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 "... ..." + ``` + +## 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 ``` -To use the output of a command, use e.g. `local text="$(get_tmux_option "@catppuccin_test_text" "#(date +%T)")"`. +To configure a custom path for your modules, set this option: -To use the output of a script, use e.g. `local text="$(get_tmux_option "@catppuccin_test_text" "#($HOME/my_script.sh)")"`. +```tmux +set -g @catppuccin_custom_plugin_dir "" +``` diff --git a/custom/example.sh b/custom/example.sh index 613caa75..3b093678 100644 --- a/custom/example.sh +++ b/custom/example.sh @@ -1,10 +1,16 @@ -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!")" +# If this module depends on an external Tmux plugin, say so in a comment. +# E.g.: Requires https://github.com/aaronpowell/tmux-weather - 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" } +