Skip to content

Commit

Permalink
chore: add README
Browse files Browse the repository at this point in the history
  • Loading branch information
dj95 committed Aug 31, 2023
1 parent ea771fc commit fd7c568
Showing 1 changed file with 124 additions and 0 deletions.
124 changes: 124 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,138 @@
<img alt="latest version" src="https://img.shields.io/github/v/tag/dj95/zjstatus.svg?sort=semver" />
</a>
<br><br>
The goal of this statusbar is to provide a highly customizable and extensible statusbar for zellij. Single
modules can be formatted separately. Due to the widget structure new modules can be created with ease.
</p>

## 🚀 Installation

Download the latest binary in the github releases. Place it somewhere, zellij is able to access it. Then the
plugin can be included by referencing it in a layout file, e.g. in the default layout one.

You could also refer to the plugin guide from zellij, after downloading the binary: [https://zellij.dev/documentation/plugin-loading](https://zellij.dev/documentation/plugin-loading)
Please ensure, that the configuration is correct.

## ⚙️ Configuration

Configuration can be performed in the layout file, when importing the plugin. Here's a short example.

```kdl
layout {
pane split_direction="vertical" {
pane
}
pane size=1 borderless=true {
plugin location="file:target/wasm32-wasi/debug/zjstatus.wasm" {
format_left "{mode} #[fg=#89B4FA,bold]{session} {tabs}"
format_right "{datetime}"
mode_normal "#[bg=#89B4FA] "
mode_tmux "#[bg=#ffc387] "
tab_normal "#[fg=#6C7086] {name} "
tab_active "#[fg=#9399B2,bold,italic] {name} "
datetime "#[fg=#6C7086,bold] {format} "
datetime_format "%A, %d %b %Y %H:%M"
}
}
}
```

In order to start using zjstatus you need to specify the widgets you'd like to use under the `format_left` and/or `format_right`
configuration. Formatting can be done with `#[..]`, while widgets and properties are surrounded by `{..}`.

### 🎨 Formatting and theming

Text and modules can be themed with directives in `#[]`. These directives tell zjstatus to print the following
text in the specified format. It will reset the format on any new directives or after rendering a widget.
Options can be combined with a `,`, when they occur in the same bracket.

Possible formatting options are:

| name | value | example | description |
|--------|-------------------|---------------|------------------|
| fg | hex or ansi color | `#[fg=#ffffff]` | foreground color |
| bg | hex or ansi color | `#[bg=#ffffff]` | background color |
| bold | none | `#[bold]` | bold text |
| italic | none | `#[italic]` | italic text |

### 🧱 Widgets

zjstatus contains the following widgets with their respective config.

#### datetime

**Handle** `{datetime}`

Print the date and/or time by the given format string.

```kdl
# theme formatting for colors. Datetime output is printed in {format}.
datetime "#[fg=#6C7086,bold] {format} "
# format of the date. e.g. if you'd like to only show the time
datetime_format "%A, %d %b %Y %H:%M"
```

#### mode

**Handle** `{mode}`

Indicate the current active mode in zellij. Each mode can be configured individually. If a mode is not configured, it will
fall back to the format of `mode_normal`. The name of the mode can be used in the `{name}` variable.

```kdl
mode_normal "#[bg=#89B4FA] {name} "
mode_locked "#[bg=#89B4FA] {name} "
mode_resize "#[bg=#89B4FA] {name} "
mode_pane "#[bg=#89B4FA] {name} "
mode_tab "#[bg=#89B4FA] {name} "
mode_scroll "#[bg=#89B4FA] {name} "
mode_enter_search "#[bg=#89B4FA] {name} "
mode_search "#[bg=#89B4FA] {name} "
mode_rename_tab "#[bg=#89B4FA] {name} "
mode_rename_pane "#[bg=#89B4FA] {name} "
mode_session "#[bg=#89B4FA] {name} "
mode_move "#[bg=#89B4FA] {name} "
mode_prompt "#[bg=#89B4FA] {name} "
mode_tmux "#[bg=#ffc387] {name} "
```

#### session

**Handle** `{session}`

Print the current session name. This module cannot be configured. For formatting, please put the Formatting
sequence right before the handle in `format_left` or `format_right`.

#### tabs

**Handle** `{tabs}`

Print a list of current tabs. The name of the tab can be used with `{name}` in the config. The active tab will
default to the normal formatting, if not configured.

```kdl
# formatting for inactive tabs
tab_normal "#[fg=#6C7086] {name} "
# formatting for the current active tab
tab_active "#[fg=#9399B2,bold,italic] {name} "
```

## 🚧 Development

Make sure you have rust and the `wasm32-wasi` target installed. If using nix, you could utilize the nix-shell
in this repo for obtaining `cargo` and `rustup`. Then you'll only need to add the target with
`rustup target add wasm32-wasi`.

With the toolchain, simply build `zjstatus` with `cargo build`. Then you are able to run the example configuration
with `zellij -l plugin-dev-workspace.kdl` from the root of the repository.

## 🤝 Contributing

If you are missing features or find some annoying bugs please feel free to submit an issue or a bugfix within a pull request :)
Expand Down

0 comments on commit fd7c568

Please sign in to comment.