Merge branch 'master' into github_actions

1 files changed, 23 insertions, 0 deletions

diff --git a/README.md b/README.md
index 94ffe1f..5e0de3e 100644
--- a/README.md
+++ b/README.md
@@ -32,3 +32,26 @@ bindsym $mod+d exec $menu
 
 ### Setup a Terminal command
 Some of your desktop entries will probably be TUI programs that expect to be launched in a new terminal window. Those entries have the `Terminal=true` flag set and you need to tell the launcher which terminal emulator to use. Pass the `TERMINAL_COMMAND` environment variable with your terminal startup command to the script to use your preferred terminal emulator. The script will default to `urxvt -e`
+
+## Extending the launcher
+
+In addition to desktop application entries and binaries, you can extend `sway-launcher-desktop` with custom item providers.
+It will read the configuration of custom item providers from `$HOME/.config/sway-launcher-desktop/providers.conf`.
+The structure looks like this:
+
+```
+[my-provider]
+list_cmd=echo -e 'my-custom-entry\034my-provider\034  My custom provider'
+preview_cmd=echo -e 'This is the preview of {1}'
+launch_cmd=notify-send 'I am now launching {1}'
+```
+
+The `list_cmd` generated the list of entries. For each entry, it has to print the following columns, separated by the `\034` field separator character:
+1. The item to launch. This will get passed to `preview_cmd` and `launch_cmd` as `{1}`
+2. The name of your provider (the same as what what you put inside the brackets, so `my-provider` in this example)
+3. The text that appears in the `fzf` window. You might want to prepend it with a glyph and add some color via ANSI escape codes
+4. (optional) Metadata that you can pass to `preview_cmd` and `launch_cmd` as `{2}`. For example, this is used to specify a specific Desktop Action inside a .desktop file
+
+The `preview_cmd` renders the contents of the `fzf` preview panel. You can use the template variable `{1}` in your command, which will be substituted with the value of the selected item.
+
+The `launch_cmd` is fired when the user has selected one of the provider's entries.
\ No newline at end of file