Skip to content

Commit

Permalink
Improve the docs to include images, and fix the slanted window style (#…
Browse files Browse the repository at this point in the history
…335)

* fix(readme): update the readme to include links, and instructions for tmux versions prior to 3.2

* feat(readme): add images for window styles, and fix the slanted style

* feat(readme): add an example config
  • Loading branch information
kjnsn authored Oct 1, 2024
1 parent b38421f commit 26b8cec
Show file tree
Hide file tree
Showing 7 changed files with 76 additions and 22 deletions.
90 changes: 72 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,9 @@
1. [Overview](#overview)
1. [Configuration options](#configuration-options)
1. [Window](#window)
1. [Window default](#window-default)
1. [Window current](#window-current)
1. [Status](#status)
1. [Pane](#pane)
1. [Customizing modules](#customizing-modules)
1. [Battery module](#battery-module)
1. [CPU module](#cpu-module)
1. [Weather modules](#weather-modules)
1. [Load module](#load-module)
1. [Create a custom module](#create-a-custom-module)
1. [Status Line](#status-line)
1. [Using the theme's built-in status modules](#using-the-themes-built-in-status-modules)
1. [Configuration Examples](#configuration-examples)
1. [Config 1](#config-1)
1. [Config 2](#config-2)
Expand All @@ -49,6 +42,10 @@
In order to have the icons displayed correctly please use/update your favorite [patched font](https://www.nerdfonts.com/font-downloads).
If you do not have a patched font installed, you can override or remove any icon. Check the documentation below on the options available.

> [!NOTE]
> If you are using a tmux version older than 3.0, you
> will need to follow the instructions for [older versions](#for-tmux-versions-prior-to-32).
### Manual (Recommended)

This method is recommended as TPM has some issues with name conflicts.
Expand All @@ -68,8 +65,8 @@ git clone https://github.com/catppuccin/tmux.git ~/.config/tmux/plugins/catppucc
4. Reload Tmux by either restarting or reloading with `tmux source ~/.tmux.conf`

> [!IMPORTANT]
> You may have to run ~/.config/tmux/plugins/tpm/bin/clean_plugins if upgrading from an earlier version
> (especially from v0.3.0).
> You may have to run `~/.config/tmux/plugins/tpm/bin/clean_plugins` if upgrading from an earlier version
> (especially from `v0.3.0`).
### TPM

Expand All @@ -89,6 +86,32 @@ set -g @plugin 'tmux-plugins/tpm'
set -g @catppuccin_flavor 'mocha' # latte, frappe, macchiato or mocha
```

### For TMUX versions prior to 3.2

This plugin uses features that were only introduced into tmux in version 3.2.
If you are using a version earlier than this, you can still have lovely catppuccin colors,
the installation method just looks a little different.

```sh
# In your ~/.tmux.conf

# Add the colors from the pallete. Check the themes/ directory for all options.

# Some basic mocha colors.
set -g @ctp_bg "#24273a"
set -g @ctp_surface_1 "#494d64"
set -g @ctp_fg "#cad3f5"
set -g @ctp_mauve "#c6a0f6"
set -g @ctp_crust "#181926"

# status line
set -gF status-style "bg=#{@ctp_bg},fg=#{@ctp_fg}"

# windows
set -gF window-status-format "#[bg=#{@ctp_surface_1},fg=#{@ctp_fg}] ##I ##T "
set -gF window-status-current-format "#[bg=#{@ctp_mauve},fg=#{@ctp_crust}] ##I ##T
```
### Upgrading from v0.3.0
If you are upgrading from 0.3.0 to any later versions, please note the following changes:
Expand All @@ -100,6 +123,37 @@ If you are upgrading from 0.3.0 to any later versions, please note the following
The plugin can be pinned to v0.3.0 if desired: `set -g @plugin 'catppuccin/tmux#v0.3.0'`.
## Recommended Default Configuration
This configuration shows some customisation options, that can be further extended as desired.
![Example configuration](./assets/example-config.webp)
```bash
# ~/.tmux.conf
# Options to make tmux more pleasant
set -g mouse on
set -g default-terminal "tmux-256color"
# Configure the catppuccin plugin
set -g @catppuccin_flavor "macchiato"
set -g @catppuccin_window_status_style "rounded"
# leave this unset to let applications set the window title
set -g @catppuccin_window_default_text " #W"
set -g @catppuccin_window_current_text " #W"
set -g @catppuccin_window_status "icon"
set -g @catppuccin_window_current_background "#{@thm_mauve}"
# Load catppuccin
run ~/.config/tmux/plugins/catppuccin/tmux/catppuccin.tmux
# Make the status line pretty and add some modules
set -g status-left ""
set -g status-right "#{E:@catppuccin_status_user}"
set -ag status-right "#{E:@catppuccin_status_directory}"
```
## Overview
![Default](./assets/overview.png)
Expand All @@ -115,13 +169,13 @@ options to your Tmux configuration.
The plugin comes with three window styles built in, these can be customized by setting the `@catppuccin_window_status_style` option. The default is `basic`.
| Option | Effect |
| --- | --- |
| `basic` | Simple styling with blocks. |
| `rounded` | Each window is separated with rounded separators. |
| `slanted` | Each window is separated with slanted separators. |
| `custom` | Custom separators are used. |
| `none` | Styling of the window status is completely disabled. |
| Option | Effect | Preview |
| --- | --- | --- |
| `basic` | Simple styling with blocks. | ![window basic](./assets/window-basic.webp) |
| `rounded` | Each window is separated with rounded separators. | ![window rounded style](./assets/window-rounded.webp) |
| `slanted` | Each window is separated with slanted separators. | ![window slanted style](./assets/window-slanted.webp) |
| `custom` | Custom separators are used. | |
| `none` | Styling of the window status is completely disabled. | ![window no styling](./assets/window-none.webp) |
If you want to change the active color to something else (the default is peach), use the following. For example to use lavender:
Expand Down
Binary file added assets/example-config.webp
Binary file not shown.
Binary file added assets/window-basic.webp
Binary file not shown.
Binary file added assets/window-none.webp
Binary file not shown.
Binary file added assets/window-rounded.webp
Binary file not shown.
Binary file added assets/window-slanted.webp
Binary file not shown.
8 changes: 4 additions & 4 deletions catppuccin_tmux.conf
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ set -ogqF @catppuccin_window_current_right_separator "#{@catppuccin_window_right
set -gq @_ctp_w_text ""

%if "#{==:#{@catppuccin_window_status},icon}"
set -gqF @_ctp_w_flags "#{E:@catppuccin_window_flags_icon_format}"
set -gqF @_ctp_w_flags "#{E:@catppuccin_window_flags_icon_format} "
%elif "#{==:#{@catppuccin_window_status},text}"
set -gq @_ctp_w_flags "#F"
%else
Expand Down Expand Up @@ -192,7 +192,7 @@ set -ogqF @catppuccin_window_current_right_separator "#{@catppuccin_window_right
set -g @_ctp_w_left \
"#[fg=#{E:@catppuccin_window_default_background},bg=default]#{@catppuccin_window_left_separator}"
set -g @_ctp_w_middle \
"#[fg=#{E:@catppuccin_window_default_background},bg=default]#{@catppuccin_window_middle_separator}"
"#[fg=#{E:@catppuccin_window_default_background},bg=#{E:@catppuccin_window_default_color}]#{@catppuccin_window_middle_separator}"
set -g @_ctp_w_number \
"#[fg=#{@thm_crust},bg=#{E:@catppuccin_window_default_background}]##I"

Expand Down Expand Up @@ -237,7 +237,7 @@ set -ogqF @catppuccin_window_current_right_separator "#{@catppuccin_window_right
# And do the same for the current window.
# =======================================

%if "#{==:#{@catppuccin_window_current_fill},none}"
%if "#{==:#{@catppuccin_window_current_fill},none}"

set -g @_ctp_w_left \
"#[fg=#{E:@catppuccin_window_current_color},bg=default]#{@catppuccin_window_current_left_separator}"
Expand All @@ -258,7 +258,7 @@ set -ogqF @catppuccin_window_current_right_separator "#{@catppuccin_window_right
set -g @_ctp_w_left \
"#[fg=#{E:@catppuccin_window_current_background},bg=default]#{@catppuccin_window_current_left_separator}"
set -g @_ctp_w_middle \
"#[fg=#{E:@catppuccin_window_current_background},bg=default]#{@catppuccin_window_current_middle_separator}"
"#[fg=#{E:@catppuccin_window_current_background},bg=#{E:@catppuccin_window_current_color}]#{@catppuccin_window_current_middle_separator}"
set -g @_ctp_w_number \
"#[fg=#{@thm_crust},bg=#{E:@catppuccin_window_current_background}]##I"

Expand Down

0 comments on commit 26b8cec

Please sign in to comment.