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>
This commit is contained in:
qadzek
GitHub
parent
4eb10fa510
commit
2a3bc9ea91
3 changed files with 75 additions and 40 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 "... <module_name> ..."
|
||||
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/<module_name>.sh` to store the custom module.
|
||||
- The file **must** end in `.sh`
|
||||
- The file **does not** need to be set as executable.
|
||||
|
||||
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.
|
||||
|
||||
```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>
|
||||
```
|
||||
|
||||
## 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>")"
|
||||
To configure a custom path for your modules, set this option:
|
||||
|
||||
local module=$( build_status_module "$index" "$icon" "$color" "$text" )
|
||||
|
||||
echo "$module"
|
||||
}
|
||||
```
|
||||
|
||||
## Configure custom modules path
|
||||
|
||||
You can configure a custom path for your modules by setting the `@catppuccin_custom_plugin_dir` option.
|
||||
```sh
|
||||
```tmux
|
||||
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)")"`.
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue