docs: new page for image preview

yazi-rs · Feb 19, 2024 · caed002 · caed002
1 parent c665c74
commit caed002
Show file tree

Hide file tree

Showing 7 changed files with 80 additions and 28 deletions.
diff --git a/cspell.json b/cspell.json
@@ -1 +1 @@
-{"language":"en","version":"0.2","flagWords":[],"words":["linemode","Hyprland","ueberzug","yazi","sxyazi","Discardable","Sixel","downscaling","downscales","keymap","unyank","preloaders","precache"]}
+{"language":"en","words":["linemode","Hyprland","ueberzug","yazi","sxyazi","Discardable","Sixel","downscaling","downscales","keymap","unyank","preloaders","precache","Konsole","Mintty","Ghostty","Zellij"],"version":"0.2","flagWords":[]}
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 description: Answers to some frequently asked questions about Yazi.
 ---
 
@@ -80,18 +80,6 @@ Before [Add `CSI 14 t` sequence support](https://github.com/crossterm-rs/crosste
 
 Therefore, the Windows edition currently uses `preview.max_width` and `preview.max_height` as the image size, which is specified by the user in the `yazi.toml` .
 
-## Why can't I preview images via Überzug++?
-
-This may be an issue with Überzug++, please try running `ueberzug layer` directly in the terminal without Yazi, and paste:
-
-```sh
-{"action":"add","identifier":"preview","max_height":0,"max_width":0,"path":"/your/image-path.jpg","x":0,"y":0}
-```
-
-into it, then press `Enter`, and to see if any image is shown, without exiting the Überzug++. Note that you need to replace `/your/image-path.jpg` with the actual path of an image.
-
-If the image shows properly when using Überzug++ independently, but not when used with Yazi, please create a bug report.
-
 ## Why do my icons shrink in [kitty](https://sw.kovidgoyal.net/kitty/), and enlarge when scrolling?
 
 TL;DR: Use a theme for Yazi, https://github.com/yazi-rs/themes

diff --git a/docs/image-preview.md b/docs/image-preview.md
@@ -0,0 +1,73 @@
+---
+sidebar_position: 4
+description: How to preview images in Yazi.
+---
+
+# Image Preview
+
+Yazi has done a lot of work to adapt to different terminals and multiplexers, trying their best to make it out-of-the-box for users.
+
+This is by no means a simple task, to reduce maintenance costs, we only guarantee it is available in the **latest version** of terminals and multiplexers (tmux, Zellij):
+
+| Platform          | Protocol                                                                                              | Support               |
+| ----------------- | ----------------------------------------------------------------------------------------------------- | --------------------- |
+| kitty             | [Kitty unicode placeholders](https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders) | ✅ Built-in           |
+| Konsole           | [Kitty old protocol](https://github.com/sxyazi/yazi/blob/main/yazi-adaptor/src/kitty_old.rs)          | ✅ Built-in           |
+| iTerm2            | [Inline images protocol](https://iterm2.com/documentation-images.html)                                | ✅ Built-in           |
+| WezTerm           | [Inline images protocol](https://iterm2.com/documentation-images.html)                                | ✅ Built-in           |
+| Mintty (Git Bash) | [Inline images protocol](https://iterm2.com/documentation-images.html)                                | ✅ Built-in           |
+| foot              | [Sixel graphics format](https://www.vt100.net/docs/vt3xx-gp/chapter14.html)                           | ✅ Built-in           |
+| Ghostty           | [Kitty old protocol](https://github.com/sxyazi/yazi/blob/main/yazi-adaptor/src/kitty_old.rs)          | ✅ Built-in           |
+| Black Box         | [Sixel graphics format](https://www.vt100.net/docs/vt3xx-gp/chapter14.html)                           | ✅ Built-in           |
+| Tabby             | [Sixel graphics format](https://www.vt100.net/docs/vt3xx-gp/chapter14.html)                           | ✅ Built-in           |
+| Hyper             | [Sixel graphics format](https://www.vt100.net/docs/vt3xx-gp/chapter14.html)                           | ✅ Built-in           |
+| X11 / Wayland     | Window system protocol                                                                                | ☑️ Überzug++ required |
+| Fallback          | [Chafa](https://hpjansson.org/chafa/)                                                                 | ☑️ Überzug++ required |
+
+Yazi automatically selects the appropriate preview method for you, based on the priority from top to bottom.
+That's relying on the `$TERM`, `$TERM_PROGRAM`, and `$XDG_SESSION_TYPE` variables, make sure you don't overwrite them by mistake!
+
+For instance, if your terminal is Alacritty, which doesn't support displaying images itself, but you are running on an X11/Wayland environment,
+it will automatically use the "Window system protocol" to display images - this requires you to have [Überzug++](https://github.com/jstkdng/ueberzugpp) installed.
+
+## tmux users
+
+To enable Yazi's image preview to work correctly in tmux, add the following 3 options to your `tmux.conf`:
+
+```sh
+set -g allow-passthrough on
+
+set -ga update-environment TERM
+set -ga update-environment TERM_PROGRAM
+```
+
+Then restart tmux (important):
+
+```sh
+tmux kill-server && tmux || tmux
+```
+
+Now you should be able to enjoy with the image preview.
+
+## Zellij users
+
+Zellij currently only supports the Sixel graphics format, so you will need a terminal that also supports Sixel.
+
+## Windows users
+
+Currently, only the following two terminals support displaying images on Windows:
+
+- WezTerm
+- Mintty (Git Bash, which comes with Git for Windows)
+
+## Why can't I preview images via Überzug++?
+
+This may be an issue with Überzug++, please try running `ueberzug layer` directly in the terminal without Yazi, and paste:
+
+```sh
+{"action":"add","identifier":"preview","max_height":0,"max_width":0,"path":"/your/image-path.jpg","x":0,"y":0}
+```
+
+into it, then press `Enter`, and to see if any image is shown, without exiting the Überzug++. Note that you need to replace `/your/image-path.jpg` with the actual path of an image.
+
+If the image shows properly when using Überzug++ independently, but not when used with Yazi, please create a bug report.
diff --git a/docs/installation.md b/docs/installation.md
@@ -100,7 +100,7 @@ Yazi relies on `file(1)` to detect the `mime-type` of the file, and the easiest
 1. Install Git for Windows by running [the official installer](https://git-scm.com/download/win), or through your package manager of choice.
 2. To allow Yazi to find `file(1)`, add `C:\Git_Installed_Directory\usr\bin\` to your `%PATH%` environment variable, which differs depending on how you installed Git:
    - If you installed Git with the installer, it would be `C:\Program Files\Git\usr\bin`.
-   - If you installed Git with scoop, it would be `C:\Users\USERNAME\scoop\apps\git\current\usr\bin`.
+   - If you installed Git with Scoop, it would be `C:\Users\USERNAME\scoop\apps\git\current\usr\bin`.
 3. Restart your terminal.
 
 To check if you've done this properly, enter `file -v`, you should see output similar to the following:
@@ -110,7 +110,7 @@ C:\Users\yazi> file -v
 file-5.45
 ```
 
-This is currently the only method we recommend. **We do NOT recommend `scoop install file`**, since Scoop's `file` cannot handle Unicode file names (such as `pexels-oliver-sjöström-1433052.jpg`) properly.
+This is **the ONLY way we recommend**. We do not recommend install it via Scoop or Chocolatey, since they cannot handle Unicode filenames (such as `oliver-sjöström.jpg`) properly and lack some required parameters.
 
 ### Installation
 
@@ -124,15 +124,6 @@ scoop install unar jq poppler fd ripgrep fzf zoxide
 
 Yazi on Scoop is maintained by community contributors, and may not always have the latest version available. You may need to check our [GitHub Releases](https://github.com/sxyazi/yazi/releases) page for the latest version.
 
-### Image previews
-
-Currently, only the following two terminals support displaying images on Windows:
-
-- WezTerm
-- Mintty (Git Bash, which comes with Git for Windows)
-
-and [Yazi has adapted them](https://github.com/sxyazi/yazi#image-preview) to work right out of the box!
-
 ## AOSC OS
 
 ```sh

diff --git a/docs/plugins/_category_.json b/docs/plugins/_category_.json
@@ -1,6 +1,6 @@
 {
 	"label": "Plugins (BETA)",
-	"position": 4,
+	"position": 5,
 	"link": {
 		"type": "doc",
 		"id": "plugins/overview"

diff --git a/docs/resources.md b/docs/resources.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 description: Some awesome plugins for Yazi.
 ---
 

diff --git a/docs/tips.md b/docs/tips.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 description: A few helpful tips for using Yazi.
 ---
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		{"language":"en","version":"0.2","flagWords":[],"words":["linemode","Hyprland","ueberzug","yazi","sxyazi","Discardable","Sixel","downscaling","downscales","keymap","unyank","preloaders","precache"]}
		{"language":"en","words":["linemode","Hyprland","ueberzug","yazi","sxyazi","Discardable","Sixel","downscaling","downscales","keymap","unyank","preloaders","precache","Konsole","Mintty","Ghostty","Zellij"],"version":"0.2","flagWords":[]}