From f2fc48c8990d26fc11d15a75004ca0f92261dee1 Mon Sep 17 00:00:00 2001 From: qadzek <84473512+qadzek@users.noreply.github.com> Date: Sat, 16 Mar 2024 22:56:55 +0100 Subject: [PATCH] Clarify creating a custom module --- README.md | 2 +- custom/README.md | 71 ++++++++++++++++++++++++++++++++--------------- custom/example.sh | 15 ++++++---- 3 files changed, 59 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 29ef238f..74bd9250 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. +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. diff --git a/custom/README.md b/custom/README.md index b4a11cb8..b168a6ce 100644 --- a/custom/README.md +++ b/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 "... ..." +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/.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 `` by the name you chose as filename. -## 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" "")" +show_() { # 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__icon" "" )" + color="$( get_tmux_option "@catppuccin__color" "$thm_orange" )" + text="$( get_tmux_option "@catppuccin__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 "" +Add the custom module to the list of modules in `.tmux.conf` + +```tmux +set -g @catppuccin_status_modules_right "... ..." ``` -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 +``` + +To configure a custom path for your modules, set this option: + +```tmux +set -g @catppuccin_custom_plugin_dir "" +``` diff --git a/custom/example.sh b/custom/example.sh index 613caa75..8a6d21c8 100644 --- a/custom/example.sh +++ b/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" } +