Add Kitty image previews to docs (#130)

1 files changed, 48 insertions, 1 deletions

diff --git a/docs/image_previews.md b/docs/image_previews.md
index c5e25be..86b240a 100644
--- a/docs/image_previews.md
+++ b/docs/image_previews.md
@@ -5,7 +5,7 @@ One reason is to keep Joshuto independent of specific display protocols and term
 However, Joshuto offers two preview-related hooks which allow to easily implement an
 image preview with some simple scripts.
 This page explains the integration with [Überzug](https://github.com/seebye/ueberzug),
-a Python tool to display images as overlays on a terminal emulator.
+a Python tool to display images as overlays on a terminal emulator, and integration with [Kitty's Icat](https://sw.kovidgoyal.net/kitty/kittens/icat/).
 This exemplary solution shows previews for JPEG and PNG files. 
 It has not been tested with MacOS and tmux.
 
@@ -223,6 +223,53 @@ display the image preview just below the textual output.
 Joshuto will have cached the textual output but all the temporary files will remain until
 Joshuto (and the wrapper script) are exited, so they will remain available for the hook scripts.
 
+# Image Previews with Kitty's Icat
+The Kitty terminal must be [installed](https://sw.kovidgoyal.net/kitty/binary/#) for the solution explained here.
+
+## Hook Scripts
+To preview images in Kitty, you need to create these two scripts and make them executable.
+
+`~/.config/joshuto/on_preview_shown`:
+```shell
+#!/usr/bin/env bash
+
+TMP_FILE="$HOME/.cache/joshuto/thumbcache.png"
+
+file="$1"
+X="$2"
+Y="$3"
+width="$4"
+height="$5"
+
+function image {
+	kitty +kitten icat --transfer-mode=file --clear 2>/dev/null
+	kitty +kitten icat --transfer-mode=file --place "${width}x${height}@${X}x${Y}" "$1" 2>/dev/null
+}
+
+case $(file -b --mime-type "${file}") in
+	image/*)
+		image "${file}"
+		;;
+esac
+```
+
+`~/.config/joshuto/on_preview_removed.sh`:
+```shell
+#!/usr/bin/env bash
+
+kitty +kitten icat --transfer-mode=file --clear 2>/dev/null
+```
+
+The first script will use icat to place an image on top of joshuto's preview window.
+If any images already exist, they will be cleared before showing the image.
+
+The second script simply clears any existing images on the screen.
+
+Thats it. Previewing images should now work whenever you select a file.
+
+## Kitty Demo: 
+![Demo](https://user-images.githubusercontent.com/57725322/150659504-203c7175-4bee-4e46-b5c5-16cc16a51a12.png)
+
 # Further Options
 By extending the scripts, image previews can also be provided for other formats, including
 videos, SVGs and whatever else. The wrapper script can be extended to provide a 2nd temporary