breaking: v0.3.0 (#28)

## Breaking changes to keybinding logic and configuration

This release moves from partially unsupported keybindings for old terminals to a _modal-based_ action trigger (fixes #12) and uses more widely supported defaults. For the motivation, see #12 and the [Customization](https://isd-project.github.io/isd/customization/) page
for details. It is recommended to _delete_ the `~/.config/isd/config.yaml` file and regenerate it if required.

"Direct" systemctl actions need to be explicitly enabled (but are still supported!).

`isd` will also check for overlapping keybindings and raise an error to minimize unexpected behaviour of the tool.

## Updated command palette

The command palette includes more descriptive help texts and mentions the associated keyboard shortcut if available.
This should help with keybinding discovery.
The documentation now explicitly mentions how to quit the application (fixes #25 and solves #21). 

## New Logo

`isd` now comes with a new logo from a hobby artist who prefers to only be referenced as Denis. Thank you Denis!

## Pager fixes

`isd` uses a more widely used `less` argument configuration to also work with older versions of `less` (fixes #22)

## Templated services

`isd` now behaves more similarly to `systemd` when viewing templated service files. To better convey that they do not provide a `Preview` output (apart from `Cat`), these units are greyed out, as suggested in #16 (fixed #16).

## Basic error recovery

If the settings cannot be correctly loaded, the error message is shown and an error log is generated. This should help users with breaking changes in the future.

.gitignore

@@ -1,6 +1,7 @@
 .helix/
 schema.json
 config.yaml
+drafts/
 result
 # config should be automatically generated when running vhs!
 docs/config/*

README.md

@@ -1,7 +1,11 @@
-# isd — *i*nteractive *s*ystem*d*
+# isd – *i*nteractive *s*ystem*d*
+
+<center>
+    <img src="./assets/isd.png" alt="isd logo" style="max-width: 50vh;">
+</center>
 
 <!-- --8<-- [start:tagline] -->
-> `isd` — a better way to work with `systemd` units
+> `isd` – a better way to work with `systemd` units
 
 Simplify `systemd` management with `isd`!
 `isd` is a TUI offering fuzzy search for units, auto-refreshing previews,
@@ -27,7 +31,7 @@ for power-users and newcomers alike.
 
 ## Demo
 
-https://github.com/user-attachments/assets/4aad0902-6094-4fc2-90b9-b62456df22f5
+https://github.com/user-attachments/assets/1f82a5c6-d6ef-4293-aa2f-347113209882
 
 [Click here for a higher quality recording](https://isd-project.github.io/isd/#working-with-isd).
 
@@ -66,6 +70,7 @@ Big thanks to the developers of:
 - [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for building a solid and simple to use static site generator for the documentation
 - [asciinema](https://docs.asciinema.org/) for developing an easy to use _and self-hostable_ terminal recorder and player
 - [vhs](https://github.com/charmbracelet/vhs) for creating a scriptable terminal program
+- [posting](https://github.com/darrenburns/posting) for showing me how to use `textual`
 <!-- --8<-- [end:acknowledgments] -->
 
 

demo.tape

@@ -96,9 +96,9 @@ Sleep 2s Space Down Down
 # Multi-selection marker
 Sleep 1s Type "]" Sleep 1s
 
-# Command palette marker
-Sleep 1s Ctrl+p Sleep 1s Type "sys" Type "]" Sleep 1s
-Type " stop" Sleep 2s Enter
+# systemctl action marker
+Sleep 1s Ctrl+o Sleep 2s Type "]" Sleep 1s
+Down Sleep 2s Enter
 
 # Auto-refresh marker
 Sleep 0.5s Type "]"
@@ -107,21 +107,25 @@ Sleep 0.5s Type "]"
 # units have stopped and updated their preview
 Sleep 4s
 
-# open pager via command palette
-Sleep 1s Ctrl+p Sleep 1s Type "open pager" Sleep 0.5s
+# Command palette marker
+Ctrl+p Sleep 1s Type "]" Sleep 1s
+
+# Command palette search marker
+Type "open pager" Sleep 1s Type "]" Sleep 1s
 Enter Sleep 0.5s
 # set marker to opened pager
 Type "]"
 Sleep 2s
-Right Right Right Right Right
+Right Right Right
 Sleep 2s
 Type "q"
 
 Sleep 2s
 
 # show journal preview marker
-Type "l" Sleep 3s Type "]"
-Sleep 1s Ctrl+p Type "open p" Sleep 1.5s
+Tab Sleep 0.5s Right
+Sleep 3s Type "]"
+Sleep 1s Ctrl+p Type "open pag" Sleep 1.5s
 Enter
 
 # set marker to journal pager
@@ -137,28 +141,28 @@ Sleep 2s Type "q" Sleep 1s
 Ctrl+p Sleep 1s Type "theme" Sleep 0.5s Enter Sleep 0.5s
 Type "dracula" Sleep 1s Enter Sleep 0.5s Type "]" Sleep 2s
 
-Type "l" Sleep 1s
+Right Sleep 1s
 # marker for Cat 
 Type "]"
 Sleep 1s
 
 # marker for Dependencies 
-Type "l" Sleep 1s 
+Right Sleep 1s 
 Type "]"
 Sleep 1s
 
 # marker for Show
-Type "l" Sleep 2s
+Right Sleep 2s
 Type "]"
 Sleep 1s
 
 # marker for Help 
-Type "l" Sleep 2s
+Right Sleep 2s
 Type "]"
 Sleep 1s
-Type "l" Sleep 2s
 
 # show status again
-Type "l" Sleep 2s
-Hide
-Ctrl+d
+Right Sleep 2s
+
+# quit marker
+Ctrl+p Type "quit" Sleep 0.5s Type "]" Sleep 0.5s Enter

docs/assets/images/isd.png

@@ -0,0 +1 @@
+../../../assets/isd.png

docs/customization.md

@@ -7,9 +7,16 @@ During start-up `isd` will read a configuration file and load those settings.
 
 By default, the configuration is read from `~/.config/isd/config.yaml`[^1].
 Though you can also simply open the file from _within_ `isd` by running the
-`Open Config` command (++alt+o++ by default).
+`Open Config` command ({{ render_shortcut(default_settings.generic_keybindings.open_config) }} by default).
 However, you will _have_ to restart `isd` for the changes to take effect!
 
+!!! warning
+
+    You need to configure the `config.yaml` file and **not** the
+    `schema.json` file. The `schema.json` file is always automatically
+    generated by `isd`. This file defines the [json-schema](https://json-schema.org/)
+    for `config.yaml` file that will only be generated via the `Open Config` command!
+
 [^1]: More precisely from `$XDG_CONFIG_DIR/isd` but for most users, it will
 default to the path above.
 
@@ -27,9 +34,7 @@ The following collapsed document shows the _entire_ default configuration:
 ??? "Default `config.yaml`"
 
     ```yaml
-
-    --8<-- "docs/config/isd/config.yaml"
-
+    {{ default_config_data | replace('\n', '\n\t') }}
     ```
 
 To not get too bored by the wall 🧱 of text, let's have a look
@@ -52,17 +57,17 @@ Just jump to the sections that sound interesting:
 - [Journal Pager](#journal-pager)
 - [Journal Pager Arguments](#journal-pager-arguments)
 - [Theme](#theme)
-- [Generic Keybindings](#generic-keybindings)
-- [Selection Keybindings](#selection-keybindings)
-- [Preview Keybindings](#preview-keybindings)
-- [`systemctl` Commands](#systemctl-commands)
+- [Keybindings](#keybindings)
+    - [Generic Keybindings](#generic-keybindings)
+    - [Main Keybindings](#main-keybindings)
+    - [Navigation Keybindings](#navigation-keybindings)
+    - [`systemctl` Keybindings](#systemctl-keybindings)
 - [Pager Arguments](#pager-arguments)
 - [Journal Pager Arguments](#journal-pager-arguments)
 - [Maximum Preview Lines](#maximum-preview-lines)
 <!--toc:end-->
 
 
-
 ### Editing The Configuration With Editor Support
 
 {{ config_block(0) }}
@@ -173,47 +178,75 @@ But to persist the changes you _must_ update the configuration file.
 <!-- [ansi escape codes](https://github.com/tinted-theming/home) -->
 <!-- you --> 
 
-### Generic Keybindings
+### Keybindings
 
-{{ config_block(11) }}
+> With great flexibility comes great responsibility.
+
+This section shows the different keybinding configuration options.
+For all entries, multiple keys can be defined by separating them with a comma `,`.
+
+!!! warning
+
+    Please note that depending on the terminal, terminal multiplexer, and
+    operating system, supported keys will vary and may require trial and error.
+
+    See <https://posting.sh/guide/keymap/#key-format> for more details.
 
-Generic keybindings are enabled _globally_ and are not limited to a specific widget.
-For example, `"ctrl+backspace"` will clear the search input and focus the search input
-widget, even if the selection or preview window is currently focused.
+`isd` is opinionated regarding _overlapping_ keybindings and will
+usually fail if keybindings are not globally unique.
+The motivation is simply to ensure that `isd` does not accidentally
+stop an important unit, just because the keybinding was overloaded and
+the focus was accidentally on a different widget.
 
-If a focused widget already defines the same keybinding, the generic keybinding
-will have a lower priority. For example, `right` would switch to the next preview window
-when the selection window is focused but it would move the cursor to the right if the
-preview log output is focused.
+#### Reserved Keys
 
-For the key format, see: <https://posting.sh/guide/keymap/#key-format>
+Please note that the following keys are _reserved_ and cannot be used
+for keybindings:
 
-### Selection Keybindings
+{{ reserved_keys_list }}
+
+#### Generic Keybindings
+
+{{ config_block(11) }}
+
+See [Keybindings](#keybindings) for more general information.
+
+#### Main Keybindings
 
 {{ config_block(12) }}
 
-Keybindings specific to the selection widget.
+See [Keybindings](#keybindings) for more general information.
 
-### Preview Keybindings
+#### Navigation Keybindings
 
 {{ config_block(13) }}
 
-Keybindings specific for the preview _log_ window.
-Note that the preview tab header is _different_ to the preview _log_ window.
+See [Keybindings](#keybindings) for more general information.
 
-### `systemctl` Commands
+#### `systemctl` Keybindings
 
 {{ config_block(14) }}
 
 This allows you to configure the `systemctl` commands and keybindings.
 It is important to note that the `command` key may contain spaces (like `edit --runtime`)
-but _does not_ include the prefix `systemctl`, since this will always be inserted.
-The full command name (for example `systemctl start`) is used for the `description` which
-will be shown in the command palette.
+but _may not_ include the prefix `systemctl`, since this will always be inserted.
+The `description` is used to provide additional information about the command
+in the command palette.
+
+!!! warning
+
+    Make sure to avoid overlaps between the [Navigation Keybindings](#navigation-keybindings)
+    and these `modal_keybinding`s and `direct_keybinding`s!
+
+Generally, it is recommended to use `ASCII` keys for the `modal_keybinding`s
+and modifier keys, such as ++ctrl++ or ++alt++, for the `direct_keybinding`s.
+
+See [Keybindings](#keybindings) for more general information.
 
 For the security implications of setting these variables see
 the [shell injection section](security.md/#shell-injection).
 
+
 ### Pager Arguments
 
 {{ config_block(15) }}