docs: improve the readability of the configuration and FAQ sections b…

…y adding more details and examples

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.

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,19 +324,45 @@ 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
 
   - `{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

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?
-
-<details>
-  <summary>Yazi Windows Edition</summary>
-  <div>
-
-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.
-
-  </div>
-</details>
-
-<details>
-  <summary>Yazi Linux Edition running on WSL</summary>
-  <div>
-
-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`.<br/>
-[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.
-
-  </div>
-</details>
-
-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

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`.<br/>
+[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`.

docs/resources.md

@@ -13,31 +13,31 @@ 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
 
 - [mime.yazi](https://github.com/DreamMaoMao/mime.yazi) - Replace the builtin `mime` plugin to speed up the identification of large files by using file extensions instead of file content to obtain the mime-types.
 
 ## 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.