From ed46ef6a5c30cf9f893452540820ed00c4f32d43 Mon Sep 17 00:00:00 2001 From: Maciej Sypien Date: Sun, 29 Sep 2024 22:04:42 +0200 Subject: [PATCH] docs: improve theme documentation and migration guide v1 to v2 --- CHANGELOG.md | 1 + README.md | 77 ++++++++++++++++++++------- docs/migration-guide-from-v1-to-v2.md | 73 +++++++++++++++++++++++++ 3 files changed, 132 insertions(+), 19 deletions(-) create mode 100644 docs/migration-guide-from-v1-to-v2.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 25c1b6b..9bb8476 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Added tests (for linux) [#39](https://github.com/egel/tmux-gruvbox/issues/39) - Added customizable statusbar [#31](https://github.com/egel/tmux-gruvbox/issues/31) - Added support for 16-bit colors palette light & dark [#34](https://github.com/egel/tmux-gruvbox/issues/34) +- Added migration guide v1 to v2 [#44](https://github.com/egel/tmux-gruvbox/issues/44) ### Changed diff --git a/README.md b/README.md index b23e5f5..acfe7e7 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@

Gruvbox theme for Tmux

-Theme with 'retro groove' flavor for [Tmux][github-tmux], based on Pavel Pertsev's [gruvbox colorscheme][github-grovbox] and inspired by work of [Gordon Chiam](https://gist.github.com/gchiam/4606522f513cc64b79ce). Subthemes switching inspired by [tmux-color-solarized][tmux-color-solarized]. +Theme with 'retro groove' flavor for [Tmux][github-tmux], based on Pavel Pertsev's [gruvbox colorscheme][github-grovbox] and inspired by work of [Gordon Chiam](https://gist.github.com/gchiam/4606522f513cc64b79ce). Subthemes switching inspired by [tmux-color-solarized][github-seebi-tmux-color-solarized].
- + [!NOTE] +> If you used v1 before and interested to adpt to v2 use this [Migration Guide from v1 to v2][docs-migration-guide-from-v1-to-v2]. + ### Install manually > [!TIP] @@ -55,26 +67,47 @@ Hit `prefix + I` to fetch the plugin and source it. Your Tmux should be updated ```bash # ~/.tmux.conf + run ~/projects/tmux-gruvbox/tmux-gruvbox.tmux # set desired options... - set -g @tmux-gruvbox 'dark' # or light + set -g @tmux-gruvbox 'dark' # or 'dark256', 'light', 'light256' ``` ## Configuration options +
+ + + +
+ ### Theme - default value: `dark256` -- available themes: - - `dark` ([preview][imgur-img-gruvbox-dark-16bit-1x]) - - `light` ([preview][imgur-img-gruvbox-light-16bit-1x]) - - `dark256` ([preview][imgur-img-gruvbox-dark256-1x]) - - `light256` ([preview][imgur-img-gruvbox-light256-1x]) + +| Theme name | Color palette | Preview link | +| :--------- | :------------ | :-------------------------------------------------------------------- | +| `dark` | 16-bit colors | preview | +| `light` | 16-bit colors | preview | +| `dark256` | 256 colors | preview | +| `light256` | 256 colors | preview | ```bash set -g @tmux-gruvbox 'dark' # dark256, light, light256 ``` +> [!TIP] +> Each terminal emulator can behave bit differently regarding displaying colors. +> If you have some problems see +> [True Color (24-bit) and italics with alacritty + tmux + vim (neovim)][github-gist-andersevenrud-alacritty-tmux-vim-truecolor] +> where there is great wisdom how to adjust my terminal, especially when used +> alacritty, tmux & neovim. + ### Transparent status-bar - default value: `'false'` @@ -86,7 +119,7 @@ set -g @tmux-gruvbox-statusbar-alpha 'true' ### Left Status (Section A) -- default value: `'#S'` +- default value: `'#S'` (session name) ```bash set -g @tmux-gruvbox-left-status-a '#S' # tmux's session name @@ -98,6 +131,10 @@ set -g @tmux-gruvbox-left-status-a '#S' # tmux's session name This section is customizable for user, and by default contains current date. +> [!TIP] +> Some user may have problem with displaying dates in desired format, if this +> case for you try using double percent `%%` + ```bash # set date in US notation set -g @tmux-gruvbox-right-status-x '%m/%d/%Y' # e.g.: 01/31/2024 @@ -121,7 +158,7 @@ set -g @tmux-gruvbox-right-status-y '%I:%M %p' # 09:54 PM ### Right Status (Section Z) -- default value: `'#h'` +- default value: `'#h'` (hostname) This section is customizable for user, and by default contains hostname. @@ -177,18 +214,20 @@ To keep the files clean we use few program to help us achieve it: GPLv3 - Maciej Sypień -[github-tmux]: https://github.com/tmux/tmux +[docs-migration-guide-from-v1-to-v2]: ./docs/migration-guide-from-v1-to-v2.md +[github-alacritty]: https://github.com/alacritty/alacritty +[github-gist-andersevenrud-alacritty-tmux-vim-truecolor]: https://gist.github.com/andersevenrud/015e61af2fd264371032763d4ed965b6 [github-grovbox]: https://github.com/morhetz/gruvbox [github-hack]: https://github.com/chrissimpkins/Hack [github-nerd-fonts]: https://github.com/ryanoasis/nerd-fonts -[github-alacritty]: https://github.com/alacritty/alacritty +[github-seebi-tmux-color-solarized]: https://github.com/seebi/tmux-colors-solarized +[github-tmux]: https://github.com/tmux/tmux [github-tpm]: https://github.com/tmux-plugins/tpm -[tmux-color-solarized]: https://github.com/seebi/tmux-colors-solarized -[pexcel-1]: https://www.pexels.com/photo/urban-photo-of-an-alley-2411688/ -[pexcel-2]: https://www.pexels.com/photo/lights-hanging-above-the-alley-in-a-city-at-night-27044195/ -[imgur-img-gruvbox-dark-light-comparision-1x]: https://i.imgur.com/uGyGwlC.png -[imgur-img-gruvbox-dark-light-comparision-0.5x]: https://i.imgur.com/p6lUnzb.png [imgur-img-gruvbox-dark-16bit-1x]: https://i.imgur.com/ae88LQI.png +[imgur-img-gruvbox-dark-light-comparision-0.5x]: https://i.imgur.com/p6lUnzb.png +[imgur-img-gruvbox-dark-light-comparision-1x]: https://i.imgur.com/uGyGwlC.png [imgur-img-gruvbox-dark256-1x]: https://i.imgur.com/kzQTTCa.png [imgur-img-gruvbox-light-16bit-1x]: https://i.imgur.com/fvpdRjg.png [imgur-img-gruvbox-light256-1x]: https://i.imgur.com/tQsl6LA.png +[pexcel-1]: https://www.pexels.com/photo/urban-photo-of-an-alley-2411688/ +[pexcel-2]: https://www.pexels.com/photo/lights-hanging-above-the-alley-in-a-city-at-night-27044195/ diff --git a/docs/migration-guide-from-v1-to-v2.md b/docs/migration-guide-from-v1-to-v2.md new file mode 100644 index 0000000..96d54cc --- /dev/null +++ b/docs/migration-guide-from-v1-to-v2.md @@ -0,0 +1,73 @@ +# Migration guide from v1 to v2 + +Hello there! + +I am so happy to see you here and being interested in using new version of +tmux-gruvbox theme. + +I really try to do all my best giving you new, interesting features that you +probably always wanted to have. + +In here I also wanted to thank you all people involved in contributing to this +theme 🙏🙇. Especially for adding all suggestions, or reporting problems if +they occurred - this helped a lot! + +## What's new? + +There are couple of great things ahead: + +- new themes supporting 16-bit color palette +- new fully customizable spaces A, X, Y, Z for your disposal +- support for transparency (experimental) +- and many more + +See what's new in [CHANGELOG][docs-changelog]. + +## Breaking changes + +I planned to have best possible user experience between migrating from v1 and v2, +therefore tried to build new changes this way to keep the breaking changes +as low as possible. This was not ideal, although I believe for many this would not +require many changes and for some none. + +### Theme names change + +| v1 | v2 | description | +| :-----------------: | :--------: | ----------------------------------------------------------------------- | +| `dark` | `dark256` | | +| `light` | `light256` | | +| `dark-transparent` | ∅ | set `dark` or `dark256` theme and add `@tmux-gruvbox-statusbar-alpha` | +| `light-transparent` | ∅ | set `light` or `light256` theme and add `@tmux-gruvbox-statusbar-alpha` | + +In v2 we've introduced a 16-bit color themes that should give the users more +happiness utilizing a greater amount of supported colors (full gruvbox palette). + +Therefore in v1 theme `light` & `dark` has been simply renamed and `256` postfix +has been added to indicate used palette. + +> [!NOTE] +> While implementing 16-bit colors I realized that many users (including me) had +> problems with setting up correct the color interpretation in their workspace +> to support multiple colors. +> +> Here is the page +> [True Color (24-bit) and italics with alacritty + tmux + vim (neovim)][github-gist-andersevenrud-alacritty-tmux-vim-truecolor] +> where I found great wisdom how to adjust my terminal, especially when used +> alacritty, tmux & neovim. + +### Fallback theme name + +| v1 | v2 | +| :----: | :-------: | +| `dark` | `dark256` | + +Continuing topic of introducing 16-bit colors, we have make slight change in +fallback theme name. We love idea adding new colors to our theme, although +during those changes we cannot forget about users whose terminals might not +support more then basic 256 colors. Therefore the fallback theme name also has +to be adapted and in v2 it's `dark256`. + +[docs-changelog]: ../CHANGELOG.md +[github-gist-andersevenrud-alacritty-tmux-vim-truecolor]: https://gist.github.com/andersevenrud/015e61af2fd264371032763d4ed965b6 + +[//]: # vi: nowrap