docs: adding for some of #70 doc (#128)

Co-authored-by: sxyazi <[email protected]>

docs/cli.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 8
+description: Data Distribution Service
+---
+
+# CLI
+
+Yazi provides a command-line tool called `ya`, which is used to assist with tasks like plugin management, flavor management, DDS message publishing and subscribing, among other features.
+
+It is an essential component of Yazi. Most distributions include it by default when installing Yazi, but if yours doesn't, you'll need to build it from source. Just be sure that the versions of both `ya` and `yazi` are exactly the same.
+
+## Package Manager
+
+You can manage your plugins and flavors using the `ya pack` subcommand. For example, to install the plugin from https://github.com/owner/my-plugin.yazi, run:
+
+```sh
+ya pack -a owner/my-plugin
+```
+
+`ya pack` also supports installing a subdirectory from a monorepo as a package. For example, to install the package from https://github.com/yazi-rs/plugins/tree/main/git.yazi, run:
+
+```sh
+ya pack -a yazi-rs/plugins:git
+```
+
+and it will automatically clone them from GitHub, copy them to your plugins directory, and update the `package.toml` to lock their versions:
+
+```toml
+# ~/.config/yazi/package.toml
+[plugin]
+deps = [
+	{ use = "owner/my-plugin", rev = "0573024" },
+	{ use = "yazi-rs/plugins:git", rev = "9a1129c" }
+]
+```
+
+To list all the plugins managed by `ya pack`:
+
+```sh
+ya pack -l
+```
+
+To install all the plugins with locked versions from `package.toml` on a new system:
+
+```sh
+ya pack -i
+```
+
+To upgrade all the plugins to the latest version:
+
+```sh
+ya pack -u
+```
+
+If you want to pin a plugin to a specific version so that it doesn't get upgraded when running `ya pack -u`, add an `=` qualifier before the hash in `rev`:
+
+```diff
+[plugin]
+deps = [
+-	{ use = "owner/my-plugin", rev = "9a1129c" }
++	{ use = "owner/my-plugin", rev = "=9a1129c" }
+]
+```

docs/configuration/keymap.md

@@ -319,11 +319,12 @@ Run a shell command.
 
 | Argument/Option | Description                                                                                                                                                                                                                              |
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[run]`         | Optional, command template to be run.                                                                                                                                                                                                    |
+| `[template]`    | Optional, command template to be run.                                                                                                                                                                                                    |
 | `--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. |
 | `--orphan`      | Keep the process running even if Yazi has exited, once specified, the process will be detached from the task scheduling system.                                                                                                          |
-| `--confirm`     | When the template is provided, run it directly, no input UI was shown. It's mutually exclusive with `--interactive`.                                                                                                                     |
-| `--interactive` | Request the user to input the command to be executed interactively. It's mutually exclusive with `--confirm`.                                                                                                                            |
+| `--confirm`     | When the template is provided, run it directly, no input box was shown. It's mutually exclusive with `--interactive`.                                                                                                                    |
+| `--interactive` | Request the user to input the command to be ran interactively. It's mutually exclusive with `--confirm`.                                                                                                                                 |
+| `--cursor`      | Set the initial position of the cursor in the interactive command input box. For example, `shell 'zip -r .zip "$0"' --cursor=7 --interactive` places the cursor before `.zip`.                                                           |
 
 You can use the following shell variables in `[run]`:
 

docs/configuration/yazi.md

@@ -192,6 +192,13 @@ This is useful for solving [a bug of Überzug++ image size calculation](https://
 
 If your monitor has a `2.0` scale factor, and is running on Wayland under Hyprland, you may need to set `ueberzug_scale: 0.5`, and adjust the value of `ueberzug_offset` according to your case, to offset this issue.
 
+### `wrap` {#preview.wrap}
+
+Wrap long lines in the preview for code preview.
+
+- `"yes"`: Enable wrapping in preview.
+- `"no"`: Disable wrapping in preview.
+
 ## [opener] {#opener}
 
 Configure available openers that can be used in [`[open]`](#open), for example:

docs/faq.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 10
+sidebar_position: 11
 description: Answers to some frequently asked questions about Yazi.
 ---
 

docs/plugins/utils.md

@@ -205,23 +205,10 @@ Preview the file as code into the specified area:
   - `skip` - The number of units to skip. It's units largely depend on your previewer, such as lines for code, and percentages for videos
   - `window` - The [Window](/docs/plugins/types#shared.window) of the preview
 
-Returns `(ok, upper_bound)`:
+Returns `(err, upper_bound)`:
 
-- `ok` - Whether the preview is successful, which is a boolean.
-- `upper_bound` - If the preview fails (`ok = false`) and it's because exceeds the maximum upper bound, return this bound; otherwise, `nil`.
-
-This function is only available in the async context.
-
-### `preview_archive(opts)` {#ya.preview_archive}
-
-Preview the file as an archive into the specified area:
-
-- `opts` - Required, the options of the preview. It's the same as [`preview_code()`](#ya.preview_code)
-
-Returns `(ok, upper_bound)`:
-
-- `ok` - Whether the preview is successful, which is a boolean.
-- `upper_bound` - If the preview fails (`ok = false`) and it's because exceeds the maximum upper bound, return this bound; otherwise, `nil`.
+- `err` - Error string if the preview fails; otherwise, `nil`.
+- `upper_bound` - If the preview fails and it's because exceeds the maximum upper bound, return this bound; otherwise, `nil`.
 
 This function is only available in the async context.
 
@@ -281,6 +268,16 @@ Truncate the text to the specified length and return it:
 
 Returns the current timestamp, which is a float, the integer part represents the seconds, and the decimal part represents the milliseconds.
 
+### `md5(str)` {#ya.md5}
+
+Calculates the MD5 of the given string.
+
+- `str` - Required, the string to be hashed.
+
+```lua
+local hash = ya.md5("Hello, World!")
+```
+
 ### `sleep(secs)` {#ya.sleep}
 
 Waits until `secs` has elapsed:
@@ -438,6 +435,45 @@ Returns `(ok, err)`:
 - `ok` - Whether the operation is successful, which is a boolean
 - `err` - The error code if the operation is failed, which is an integer if any
 
+### `remove(type, url)` {#fs.remove}
+
+```lua
+local ok, err = fs.remove("file", Url("/tmp/test.txt"))
+```
+
+Remove the specified file(s) from the filesystem:
+
+- `type` - Required, the type of removal, which can be:
+  - `"file"` - Removes a file from the filesystem.
+  - `"dir"` - Removes an existing, empty directory.
+  - `"dir_all"` - Removes a directory at this url, after removing all its contents. Use carefully!
+  - `"dir_clean"` - Remove all empty directories under it, and if the directory itself is empty afterward, remove it as well.
+- `url` - Required, the [Url](/docs/plugins/types#shared.url) of the target.
+
+Returns `(ok, err)`:
+
+- `ok` - Whether the operation is successful, which is a boolean
+- `err` - The error code if the operation is failed, which is an integer if any
+
+### `read_dir(url, options)` {#fs.read_dir}
+
+```lua
+local files, err = fs.read_dir("url", { limit = 10 })
+```
+
+Reads the contents of a directory:
+
+- `url` - Required, the [Url](/docs/plugins/types#shared.url) of the directory.
+- `options` - Optional, a table with the following options:
+  - `glob` - A glob pattern to filter files out if provided.
+  - `limit` - The maximum number of files to read, which is an integer, defaults to unlimited.
+  - `resolve` - Whether to resolve symbolic links, defaults to `false`.
+
+Returns `(files, err)`:
+
+- `files` - A table of [File](/docs/plugins/types#shared.file) if successful; otherwise, `nil`.
+- `err` - The error code if the operation is failed, which is an integer if any.
+
 ### `cha(url, follow)` {#fs.cha}
 
 ```lua
@@ -585,6 +621,17 @@ Spawn the command and wait for it to finish, returns `(output, err)`:
 - `output` - The [Output](#output) of the command if successful; otherwise, `nil`
 - `err` - The error code if the operation is failed, which is an integer if any
 
+### `status()` {#Command.status}
+
+```lua
+local status, err = Command("ls"):status()
+```
+
+Executes the command as a child process, waiting for it to finish and collecting its exit status. Returns `(status, err)`:
+
+- `status` - The [Status](#status) of the child process if successful; otherwise, `nil`
+- `err` - The error code if the operation is failed, which is an integer if any
+
 ## Child
 
 This object is created by [`Command:spawn()`](#Command.spawn) and represents a running child process.

docs/resources.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 description: Some awesome plugins for Yazi.
 ---
 
@@ -141,7 +141,7 @@ Vim:
 ## 🐚 Shell plugins {#shell}
 
 - [yazi-prompt.sh](https://github.com/Sonico98/yazi-prompt.sh) - Display an indicator in your prompt when running inside a yazi subshell.
-- [custom-shell.yazi](https://github.com/AnirudhG07/custom-shell.yazi) - Set your custom-shell as your default yazi Shell.
+- [custom-shell.yazi](https://github.com/AnirudhG07/custom-shell.yazi) - Run any commands through your default system shell.
 - [command.yazi](https://github.com/KKV9/command.yazi) - Display a prompt for executing yazi commands.
 
 ## 🛠️ Utilities {#utilities}

docs/tips.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 description: A few helpful tips for using Yazi.
 ---