From d706c36ae131aafeb0f1a573e3e7639ca1daf1bc Mon Sep 17 00:00:00 2001 From: sxyazi Date: Thu, 22 Feb 2024 06:57:14 +0800 Subject: [PATCH] docs: improve the readability of the configuration and FAQ sections by adding more details and examples --- docs/configuration/keymap.md | 11 +++++-- docs/configuration/yazi.md | 48 ++++++++++++++++++++++------- docs/faq.md | 58 +++++++----------------------------- docs/image-preview.md | 28 +++++++++++++++++ docs/resources.md | 16 +++++----- 5 files changed, 92 insertions(+), 69 deletions(-) diff --git a/docs/configuration/keymap.md b/docs/configuration/keymap.md index cd2e7a5d..c77508cc 100644 --- a/docs/configuration/keymap.md +++ b/docs/configuration/keymap.md @@ -177,10 +177,10 @@ Enter visual mode (selection mode). Open the selected files. -| Options/Arguments | Description | -| ----------------- | ---------------------------------------------------------------------------- | +| Options/Arguments | Description | +| ----------------- | -------------------------------------------------------------------------------------- | | `--interactive` | Open the hovered/selected file(s) with an interactive UI to choose the opening method. | -| `--hovered` | Always open the hovered file regardless of the selection state. | +| `--hovered` | Always open the hovered file regardless of the selection state. | ### `yank` @@ -271,6 +271,11 @@ Run a shell command. | `--block` | Open in a blocking manner. After setting this, Yazi will hide into a secondary screen and display the program on the main screen until it exits. During this time, it can receive I/O signals, which is useful for interactive programs. | | `--confirm` | When the template is provided, run it directly, no input UI was shown. | +You can use the following shell variables in `[exec]`: + +- `$n` (Unix) / `%n` (Windows): The N-th selected file, starting from `1`. e.g. `$2` represents the second selected file. +- `$@` (Unix) / `%*` (Windows): All selected files. + ### `hidden` Set the visibility of hidden files. diff --git a/docs/configuration/yazi.md b/docs/configuration/yazi.md index d92c0a9b..12e67c0d 100644 --- a/docs/configuration/yazi.md +++ b/docs/configuration/yazi.md @@ -154,9 +154,8 @@ text = [ Available parameters are as follows: - exec: The command to open the selected files, with the following variables available: - - `$n` (Unix) / `%n` (Windows): The N-th selected file, starting from 1 - - `$@` (Unix) / `%*` (Windows): All selected files - - `foo`: Literal string to be passed + - `$n` (Unix) / `%n` (Windows): The N-th selected file, starting from `1`. e.g. `$2` represents the second selected file. + - `$@` (Unix) / `%*` (Windows): All selected files. - block (Boolean): Open in a blocking manner. After setting this, Yazi will hide into a secondary screen and display the program on the main screen until it exits. During this time, it can receive I/O signals, which is useful for interactive programs. - orphan (Boolean): Keep the process running even if Yazi has exited. - desc: Description of the opener, displayed in the selection menu. @@ -208,10 +207,13 @@ Maximum number of retries when a bizarre failure occurs. Exclude the preload tasks created by the system from the task list, do not report their progress, and do not consider them on app exit confirming. -### Image decoding +### `image_alloc` -- image_alloc: Maximum memory allocation limit (in bytes) for decoding a single image, `0` for unlimited. -- image_bound(`[width, height]`): Maximum image size (in pixels) for decoding a single image, `0` for unlimited. +Maximum memory allocation limit in bytes for decoding a single image, `0` for unlimited. + +### `image_bound` + +An array of `[width, height]`, maximum image size (in pixels) for decoding a single image, and `0` for unlimited. ## [plugin] @@ -286,9 +288,9 @@ If you want to create your own preloader, see [Preloader API](../plugins/overvie ## [input] -You can customize the title and position of each `Input`. As for position, it consists of two parts: [Origin](#origin) and [Offset](#offset). +You can customize the title and position of each input. As for position, it consists of two parts: [Origin](#origin) and [Offset](#offset). -The origin is the top-left corner of the `Input`, and the offset is the increment from this origin. Together, they determine the area of the `Input` on the screen. +The origin is the top-left corner of the input, and the offset is the increment from this origin. Together, they determine the area of the input on the screen. ### Origin @@ -309,7 +311,7 @@ As for the offset, it's a 4-element tuple: `(x, y, width, height)`. ### Placeholder -Some `Input`s have special placeholders that will be replaced with actual content on display: +Some inputs have special placeholders that will be replaced with actual content on display: - trash_title: String @@ -322,6 +324,7 @@ Some `Input`s have special placeholders that will be replaced with actual conten - `{s}`: `"s"` if `n > 1`, otherwise `""` - find_title: [String, String] + It's a tuple of 2-element: first for "Find next", second for "Find previous". - search_title: String @@ -329,12 +332,37 @@ Some `Input`s have special placeholders that will be replaced with actual conten - `{n}`: Name of the current search engine - shell_title: [String, String] + It's a tuple of 2-element: first for "Non-blocking shell", second for "Blocking shell". -- quit_title +- quit_title: String - `{n}`: Number of tasks are running - `{s}`: `"s"` if `n > 1`, otherwise `""` ## [select] Same as [the input](#input). + +## [which] + +### `sort_by` + +Candidate sorting method. + +- `"none"`: Don't sort. +- `"key"`: Sort by key. +- `"desc`: Sort by description. + +### `sort_sensitive` + +Sort case-sensitively. + +- `true`: Case-sensitive +- `false`: Case-insensitive + +### `sort_reverse` + +Display candidates in reverse order. + +- `true`: Reverse order +- `false`: Normal order diff --git a/docs/faq.md b/docs/faq.md index fde87002..72466a0f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -9,12 +9,18 @@ description: Answers to some frequently asked questions about Yazi. See [Why is Yazi fast?](/blog/why-is-yazi-fast). -## Why am I getting a "Permission denied" when editing files in Linux/macOS? +## Why can't I edit text files? -Yazi defaults to using `$EDITOR` as the default editor, which is suitable for most cases. +Yazi defaults to using `$EDITOR` as the text editor for Linux/macOS. +If you are unable to edit files, please check your Bash/Zsh/Fish configuration file for settings like `export EDITOR=vim`. You can also [change Yazi's text opener](/docs/configuration/yazi#opener) from `$EDITOR` to vim/nvim/nano. -When you encounter this error, it means that `$EDITOR` is not set properly. You can add something like `export EDITOR=vim` to your Bash/Zsh/Fish configuration. -Alternatively, you can change Yazi's [default edit opener](https://github.com/sxyazi/yazi/blob/main/yazi-config/preset/yazi.toml) from `$EDITOR` to vim/nvim/nano. +For Windows, there is no concept of `$EDITOR`, so users need to modify the text opener as needed. + +## Why can't I open/edit/preview files on Windows? + +Have you added Git to the `PATH` as per the [Windows Requirements](/docs/installation#requirements)? + +Please make sure the `file` command is available in your terminal, you can do a `file -v` to check it. ## Why is my text color not distinct? @@ -36,50 +42,6 @@ This is true for a actual directory as well - a directory can be entered (in Yaz If you truly don't need to distinguish between them, use this [smart-enter tip](/docs/tips.md#smart-enter-enter-for-directory-open-for-file). -## Why can't I preview files on Windows? - -
- Yazi Windows Edition -
- -Have you added Git to the `PATH` according to the [Windows Installation Guide](/docs/installation#windows)? - -Please make sure the `file` command is available in your terminal, you can do a `file -v` to verify it. - -
-
- -
- Yazi Linux Edition running on WSL -
- -Limited by ConPTY, the Windows edition has had to implement many workarounds, which are not perfect. - -However, if you run Yazi in WSL, you can experience perfect image previews using `wezterm ssh`.
-[WezTerm](https://wezfurlong.org/wezterm/) is an excellent terminal that can bypass the limitations of ConPTY through its SSH feature, and it's currently the only terminal that supports this approach. - -You need to install `sshd` in WSL and start it: - -```sh -sudo apt install openssh-server -sudo service ssh restart -``` - -Then, on the host machine, connect to WSL via SSH: - -```sh -wezterm ssh 127.0.0.1 -``` - -That's it! you can now get Yazi's image preview working properly. - -
-
- -Before [Add `CSI 14 t` sequence support](https://github.com/crossterm-rs/crossterm/pull/810) is merged, it is not possible to obtain the actual width and height of the terminal. - -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 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 index 7786aefd..6513cc92 100644 --- a/docs/image-preview.md +++ b/docs/image-preview.md @@ -60,6 +60,28 @@ Currently, only the following two terminals support displaying images on Windows - WezTerm - Mintty (Git Bash, which comes with Git for Windows) +## Windows with WSL users + +Limited by ConPTY, the Windows edition has had to implement many workarounds, which are not perfect. + +However, if you run Yazi in WSL, you can experience perfect image previews using `wezterm ssh`.
+[WezTerm](https://wezfurlong.org/wezterm/) is an excellent terminal that can bypass the limitations of ConPTY through its SSH feature, and it's currently the only terminal that allows this approach. + +You need to install `sshd` in WSL and start it: + +```sh +sudo apt install openssh-server +sudo service ssh restart +``` + +Then, on the host machine, connect to WSL over SSH: + +```sh +wezterm ssh 127.0.0.1 +``` + +That's it! you can now get Yazi's image preview working properly. + ## 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: @@ -71,3 +93,9 @@ This may be an issue with Überzug++, please try running `ueberzug layer` direct 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 won't my images adapt to terminal size? + +Some terminals (such as VSCode, Tabby, and all Windows terminals) do not implement the `ioctl` system call, before [Add `CSI 14 t` sequence support](https://github.com/crossterm-rs/crossterm/pull/810) is merged, it is not possible to obtain the actual pixel width and height of the terminal. + +Therefore, Yazi uses `preview.max_width` and `preview.max_height` as the image size, which is specified by the user in `yazi.toml`. diff --git a/docs/resources.md b/docs/resources.md index 1c82b73e..68ef65da 100644 --- a/docs/resources.md +++ b/docs/resources.md @@ -13,19 +13,19 @@ The plugin system is still in the early stage, and most of the plugins below onl Markdown: -- [glow.yazi](https://github.com/Reledia/glow.yazi) - Preview markdown files using [glow](https://github.com/charmbracelet/glow) +- [glow.yazi](https://github.com/Reledia/glow.yazi) - Preview markdown files using [glow](https://github.com/charmbracelet/glow). CSV: -- [miller.yazi](https://github.com/Reledia/miller.yazi) - Preview CSV files (and other supported formats) using [miller](https://github.com/johnkerl/miller) +- [miller.yazi](https://github.com/Reledia/miller.yazi) - Preview CSV files (and other supported formats) using [miller](https://github.com/johnkerl/miller). Binary: -- [hexyl.yazi](https://github.com/Reledia/hexyl.yazi) - Using [hexyl](https://github.com/sharkdp/hexyl) as the fallback previewer for files +- [hexyl.yazi](https://github.com/Reledia/hexyl.yazi) - Using [hexyl](https://github.com/sharkdp/hexyl) as the fallback previewer for files. Audio: -- [exifaudio.yazi](https://github.com/Sonico98/exifaudio.yazi) - Preview audio metadata and cover using [exiftool](https://exiftool.org/) +- [exifaudio.yazi](https://github.com/Sonico98/exifaudio.yazi) - Preview audio metadata and cover using [exiftool](https://exiftool.org/). ## Preloaders @@ -33,11 +33,11 @@ Audio: ## Functional plugins -- [keyjump.yazi](https://github.com/DreamMaoMao/keyjump.yazi) - A yazi plugin like flash.nvim, allows precise navigation using single (or double) characters. +- [keyjump.yazi](https://github.com/DreamMaoMao/keyjump.yazi) - A Yazi plugin like flash.nvim, allows precise navigation using single (or double) characters. - [bookmarks.yazi](https://github.com/dedukun/bookmarks.yazi) - A Yazi plugin that adds the basic functionality of Vi-like marks. ## Neovim plugins -- [tfm.nvim](https://github.com/Rolv-Apneseth/tfm.nvim) - Neovim plugin for terminal file manager integration -- [yazi.nvim](https://github.com/DreamMaoMao/yazi.nvim) - A Neovim Plugin for yazi terminal file browser -- [fm-nvim](https://github.com/Eric-Song-Nop/fm-nvim) - Neovim plugin that lets you use your favorite terminal file managers +- [tfm.nvim](https://github.com/Rolv-Apneseth/tfm.nvim) - Neovim plugin for terminal file manager integration. +- [yazi.nvim](https://github.com/DreamMaoMao/yazi.nvim) - A Neovim Plugin for yazi terminal file browser. +- [fm-nvim](https://github.com/Eric-Song-Nop/fm-nvim) - Neovim plugin that lets you use your favorite terminal file managers.