From 393f7fbf32f63ae5fe820f7a514efdde630fd444 Mon Sep 17 00:00:00 2001
From: Vladimir Panteleev <git@cy.md>
Date: Tue, 13 Aug 2024 22:47:22 +0000
Subject: [PATCH 1/2] docs/plugins/overview: Mention plugins loaded from
 init.lua

---
 docs/plugins/overview.md | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md
index 24227760..70e8feae 100644
--- a/docs/plugins/overview.md
+++ b/docs/plugins/overview.md
@@ -38,11 +38,25 @@ Where:
 
 ## Usage {#usage}
 
-A plugin has two usages:
+Plugins generally can have three usages:
 
+- [Utility plugin](#utility-plugin): Load them in your `init.lua`.
 - [Functional plugin](#functional-plugin): Bind the `plugin` command to a key in `keymap.toml`, and activate it by pressing the key.
 - [Custom previewers, preloaders](/docs/configuration/yazi#plugin): Configure them as `previewers` or `preloaders` in your `[plugin]` of `yazi.toml` file.
 
+### Utility plugin {#utility-plugin}
+
+Such plugins can be loaded by `require`-ing them in your `init.lua`, for example:
+
+```lua
+-- ~/.config/yazi/init.lua
+require("zoxide"):setup {
+  update_db = true,
+}
+```
+
+These plugins will usually [subscribe to events](/docs/plugins/utils/#ps.sub) and work in the background.
+
 ### Functional plugin {#functional-plugin}
 
 You can bind a `plugin` command to a specific key in your `keymap.toml` with:

From 9509c14b8aff5d1ed0e7d0d653189ffd190d26a3 Mon Sep 17 00:00:00 2001
From: Vladimir Panteleev <git@cy.md>
Date: Tue, 13 Aug 2024 22:47:42 +0000
Subject: [PATCH 2/2] docs/plugins/overview: Explain sync/async a bit more

---
 docs/plugins/overview.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md
index 70e8feae..00533327 100644
--- a/docs/plugins/overview.md
+++ b/docs/plugins/overview.md
@@ -83,9 +83,9 @@ return {
 
 ## Sync vs Async {#sync-vs-async}
 
-The plugin system is designed with an async-first philosophy. Therefore, unless specifically specified, such as the `--sync` for the `plugin` command, all plugins run in an async context.
+The plugin system is designed with an async-first philosophy. Therefore, unless specifically specified, such as the `--sync` for the `plugin` command, plugin code runs in an async context.
 
-There is one exception - all `init.lua` are synchronous, which includes:
+There is one exception - all top-level statements in `init.lua` files are synchronous, which includes:
 
 - The `init.lua` for Yazi itself, i.e. `~/.config/yazi/init.lua`.
 - The `init.lua` for each plugin, e.g. `~/.config/yazi/plugins/bar.yazi/init.lua`.
@@ -142,7 +142,7 @@ i = 2
 
 ### Async context {#async-context}
 
-When a plugin is executed asynchronously, an isolated async context is created for it automatically.
+When a plugin function is executed asynchronously (as is the default), an isolated async context is created for it automatically.
 
 In this context, you can use all the async functions supported by Yazi, and it operates concurrently with the main thread, ensuring that the main thread is not blocked.
 
@@ -173,6 +173,10 @@ return {
 }
 ```
 
+`ya.sync` wraps a user-supplied function that operates in the sync context, and returns a function callable from an async context.
+When the wrapped function is thus called from an async context, it will run the wrapped code inside the sync context,
+propagating the return value to the caller back in the async context.
+
 Note that `ya.sync()` call must be at the top level:
 
 ```lua