Skip to content

Commit

Permalink
docs: update configuration and resources docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@sxyazi
sxyazi committed Aug 3, 2024
1 parent 0930026 commit 4b2a645
Show file tree
Hide file tree
Showing 5 changed files with 51 additions and 42 deletions.
15 changes: 8 additions & 7 deletions docs/configuration/keymap.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -334,13 +334,14 @@ Set the visibility of hidden files.

Set the [line mode](/docs/configuration/yazi#manager.linemode).

| Argument/Option | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none` | No line mode. |
| `size` | Display the size in bytes of the file. Since file sizes are only evaluated when sorting by size, it only works after [`sort_by = "size"`](/docs/configuration/yazi#manager.sort_by) set, and this behavior might change in the future. |
| `permissions` | Display the permissions of the file, only available on Unix-like systems. |
| `mtime` | Display the last modified time of the file. |
| `owner` | Display the owner of the file, only available on Unix-like systems. |
| Argument/Option | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none` | No line mode. |
| `size` | Display the size in bytes of the file. Note that currently directory sizes are only evaluated when [`sort_by = "size"`](/docs/configuration/yazi#manager.sort_by), and this might change in the future. |
| `ctime` | Display the creation time of the file. |
| `mtime` | Display the last modified time of the file. |
| `permissions` | Display the permissions of the file, only available on Unix-like systems. |
| `owner` | Display the owner of the file, only available on Unix-like systems. |

### `search` {#manager.search}

Expand Down
22 changes: 12 additions & 10 deletions docs/configuration/theme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Appears in a format similar to `{ fg = "#e4e4e4", bg = "black", ... }`, and supp

## [flavor] {#flavor}

- use (String): Flavor name, e.g. `"Dracula"`. See [flavor documentation](/docs/flavors/overview) for more details.
- use (String): Flavor name, e.g. `"dracula"`. See [flavor documentation](/docs/flavors/overview) for more details.

## [manager] {#manager}

Expand Down Expand Up @@ -220,18 +220,18 @@ Each icon rule contains the following properties:

Icons are matched according to the following priority:

- globs: glob expressions, e.g., `{ name = "**/Downloads/*.zip", ... }`
- dirs: directory names, e.g., `{ name = "Desktop", ... }`
- files: file names, e.g., `{ name = ".bashrc", ... }`
- exts: extensions, e.g., `{ name = "mp3", ... }`
- conds: conditions, e.g., `{ if = "!dir", ... }`
1. globs: glob expressions, e.g., `{ name = "**/Downloads/*.zip", ... }`
2. dirs: directory names, e.g., `{ name = "Desktop", ... }`
3. files: file names, e.g., `{ name = ".bashrc", ... }`
4. exts: extensions, e.g., `{ name = "mp3", ... }`
5. conds: conditions, e.g., `{ if = "!dir", ... }`

`dirs`, `files`, and `exts` are compiled into a `HashMap` at startup, offering `O(1)` time complexity for very fast lookups, which should meet most needs.
`dirs`, `files`, and `exts` are compiled into a HashMap at startup, offering O(1) time complexity for very fast lookups, which should meet most needs.

For more complex and precise rules, such as matching a specific file in a specific directory, use `globs` - these are always executed first to check if any rules in the glob set are met.
However, they are much slower than `dirs`, `files`, and `exts`, so it's not recommended to use them excessively.

If none of the above rules match, it will fallback to `conds` to check if any specific conditions are met. `conds` are mostly used for rules related to file metadata, and includes the following conditional factors:
If none of the above rules match, it will fallback to `conds` to check if any specific conditions are met. `conds` are mostly used for rules related to file metadata, which includes the following conditional factors:

- `dir`: The file is a directory
- `hidden`: The file is hidden
Expand All @@ -246,24 +246,25 @@ If none of the above rules match, it will fallback to `conds` to check if any sp
- `sticky`: The file has the sticky bit set

Yazi has builtin support for [nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons), a rich set of icons ready to use.
If you want to add your own rules to this set, you can use `prepend_*` and `append_*` to prepend or append rules to the default ones (see [Configuration Mixing](/docs/configuration/overview#mixing) for details), e.g.:
If you want to add your own rules to this set, you can use `prepend_*` and `append_*` to prepend or append rules to the default ones (see [Configuration Mixing](/docs/configuration/overview#mixing) for details):

```toml
[icon]
prepend_dirs = [
{ name = "desktop", text = "", fg_dark = "#563d7c", fg_light = "#563d7c" },
# ...
]

append_exts = [
{ name = "mp3", text = "", fg_dark = "#00afff", fg_light = "#0075aa" },
# ...
]
# ...
```

If you want to completely override the default rules, you can do so with:

```toml
[icon]
dirs = [
{ name = "desktop", text = "", fg_dark = "#563d7c", fg_light = "#563d7c" },
# ...
Expand All @@ -272,4 +273,5 @@ exts = [
{ name = "mp3", text = "", fg_dark = "#00afff", fg_light = "#0075aa" },
# ...
]
# ...
```
5 changes: 3 additions & 2 deletions docs/configuration/yazi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,10 @@ This is useful for files that contain Hungarian characters.
Line mode: display information associated with the file on the right side of the file list row.

- `"none"`: No line mode.
- `"size"`: Display the size in bytes of the file. Since file sizes are only evaluated when sorting by size, it only works after [`sort_by = "size"`](/docs/configuration/yazi#manager.sort_by) set, and this behavior might change in the future.
- `"permissions"`: Display the permissions of the file, only available on Unix-like systems.
- `"size"`: Display the size in bytes of the file. Note that currently directory sizes are only evaluated when [`sort_by = "size"`](/docs/configuration/yazi#manager.sort_by), and this might change in the future.
- `"ctime"`: Display the creation time of the file.
- `"mtime"`: Display the last modified time of the file.
- `"permissions"`: Display the permissions of the file, only available on Unix-like systems.
- `"owner"`: Display the owner of the file, only available on Unix-like systems.

You can also specify any 1 to 20 characters, and extend it within a UI plugin, which means you can implement your own linemode through the plugin system like this:
Expand Down
47 changes: 26 additions & 21 deletions docs/plugins/utils.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -237,13 +237,32 @@ This function is only available in the async context.

### `target_family()` {#ya.target_family}

Returns the target family of the current platform, `"windows"`, `"unix"`, or `"wasm"`.
Returns the family of the operating system. Some possible values:

- `"unix"`
- `"windows"`
- `"wasm"`

### `target_os()` {#ya.target_os}

Returns a string describing the specific operating system in use. Some possible values:

- `"linux"`
- `"macos"`
- `"ios"`
- `"freebsd"`
- `"dragonfly"`
- `"netbsd"`
- `"openbsd"`
- `"solaris"`
- `"android"`
- `"windows"`

### `quote(str)` {#ya.quote}

Quote characters that may have special meaning in a shell:

- `str`: Required, the string to be quoted, which is a string
- `str`: Required, the string to be quoted

```lua
local handle = io.popen("ls " .. ya.quote(filename))
Expand Down Expand Up @@ -438,30 +457,16 @@ 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

### `cha(url)` {#fs.cha}
### `cha(url, follow)` {#fs.cha}

```lua
local cha, err = fs.cha(url)
```

Get the [Cha](/docs/plugins/types#shared.cha) of the specified file, which is faster than [`cha_follow()`](#fs.cha_follow) since it never follows the symbolic link:

- `url` - Required, the [Url](/docs/plugins/types#shared.url) of the file

Returns `(cha, err)`:

- `cha` - The [Cha](/docs/plugins/types#shared.cha) of the file if successful; otherwise, `nil`
- `err` - The error code if the operation is failed, which is an integer if any

### `cha_follow(url)` {#fs.cha_follow}

```lua
local cha, err = fs.cha_follow(url)
```

Get the [Cha](/docs/plugins/types#shared.cha) of the specified file, and follow the symbolic link:
Get the [Cha](/docs/plugins/types#shared.cha) of the specified file:

- `url` - Required, the [Url](/docs/plugins/types#shared.url) of the file
- `follow` - Optional, whether to follow the symbolic link, which is a boolean

Returns `(cha, err)`:

Expand Down Expand Up @@ -716,7 +721,7 @@ See [`take_stdout()`](/docs/plugins/utils#Child.take_stdout) for an example.
local ok, err = child:write_all(src)
```

Writes all bytes from the string `src` to the stdin of the child process, returns:
Writes all bytes from the string `src` to the stdin of the child process, 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
Expand All @@ -734,7 +739,7 @@ otherwise, an error will be thrown.
local ok, err = child:flush()
```

Flushes any buffered data to the stdin of the child process, returns:
Flushes any buffered data to the stdin of the child process, 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
Expand Down
4 changes: 2 additions & 2 deletions docs/resources.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ File actions:

- [chmod.yazi](https://github.com/yazi-rs/plugins/tree/main/chmod.yazi) - Execute `chmod` on the selected files to change their mode.
- [diff.yazi](https://github.com/yazi-rs/plugins/tree/main/diff.yazi) - Diff the selected file with the hovered file, create a living patch, and copy it to the clipboard.
- [archive.yazi](https://github.com/KKV9/archive.yazi) - Compress selected or hovered files and directories to an archive. It currently supports various archive formats.
- [compress.yazi](https://github.com/KKV9/compress.yazi) - A Yazi plugin that compresses selected files to an archive.
- [ouch.yazi](https://github.com/ndtoan96/ouch.yazi) - An [ouch](https://github.com/ouch-org/ouch) plugin for Yazi, supporting preview and compression.
- [archivemount.yazi](https://github.com/AnirudhG07/archivemount.yazi) - Mounting and unmounting archives in yazi using [archivemount](https://github.com/cybernoid/archivemount).
- [reflink.yazi](https://github.com/Ape/reflink.yazi) - Create reflinks to files.
Expand Down Expand Up @@ -99,8 +99,8 @@ Images:

Neovim:

- [yazi.nvim](https://github.com/mikavilpas/yazi.nvim) - A Neovim plugin for the yazi terminal file manager.
- [tfm.nvim](https://github.com/Rolv-Apneseth/tfm.nvim) - Neovim plugin for terminal file manager integration.
- [yazi.nvim](https://github.com/mikavilpas/yazi.nvim) - A fork of DreamMaoMao/yazi.nvim with a bunch of additional features.
- [fm-nvim](https://github.com/Eric-Song-Nop/fm-nvim) - Neovim plugin that lets you use your favorite terminal file managers.

Vim:
Expand Down

0 comments on commit 4b2a645

Please sign in to comment.