From 507649aa4a60d12e88a1d1e95ba318b07065797d Mon Sep 17 00:00:00 2001
From: sxyazi <sxyazi@gmail.com>
Date: Thu, 29 Feb 2024 11:05:49 +0800
Subject: [PATCH] docs: switch flavors to BETA and update the note

---
 docs/flavors/_category_.json |  2 +-
 docs/flavors/overview.md     | 20 ++++++++++++--------
 docs/plugins/overview.md     | 22 ++++++++++++++--------
 docs/resources.md            |  2 +-
 4 files changed, 28 insertions(+), 18 deletions(-)

diff --git a/docs/flavors/_category_.json b/docs/flavors/_category_.json
index 14f1aca2..6bfd74ab 100644
--- a/docs/flavors/_category_.json
+++ b/docs/flavors/_category_.json
@@ -1,5 +1,5 @@
 {
-	"label": "Flavors (WIP)",
+	"label": "Flavors (BETA)",
 	"position": 6,
 	"link": {
 		"type": "doc",
diff --git a/docs/flavors/overview.md b/docs/flavors/overview.md
index c1fcacdc..9244fdab 100644
--- a/docs/flavors/overview.md
+++ b/docs/flavors/overview.md
@@ -1,18 +1,22 @@
 ---
 id: overview
 sidebar_position: 0
-sidebar_label: Flavors (WIP)
+sidebar_label: Flavors (BETA)
 description: Learn how to use Yazi flavors.
 ---
 
-# Flavors (WIP)
+# Flavors (BETA)
+
+:::note
+The flavors is still in early stages, and currently only available in the latest main branch.
+:::
 
 The "flavor" is a pre-made Yazi theme, while what we typically refer to as a "theme" is the user's own theme, i.e. `~/.config/yazi/theme.toml` file.
 
 The purpose of separating them is to allow users to customize their preferences more conveniently on top of an existing flavor, without having to modify those flavor files.
 This makes it easier to update, as there won't be conflicts when pulling from Git.
 
-Behind the scenes, Yazi merges the user's `theme.toml` with the flavor's `theme.toml` automatically, and the user's always takes precedence over the flavor.
+Behind the scenes, Yazi merges the user's `theme.toml` with the flavor's `flavor.toml` automatically, and the user's always takes precedence over the flavor.
 
 ## Directory structure
 
@@ -29,23 +33,23 @@ These flavors are placed in the `flavors` subdirectory of the Yazi configuration
 └── theme.toml
 ```
 
-Each flavor is a directory ending with `.yazi`, containing at least the following files:
+Each flavor is a directory with a hyphen-separated name, ending in `.yazi`, and containing at least the following files:
 
 ```
 bar.yazi/
-├── theme.toml
+├── flavor.toml
 ├── tmtheme.xml
-├── screenshot.png
 ├── README.md
+├── screenshot.png
 ├── LICENSE
 └── LICENSE-tmtheme
 ```
 
 Where:
 
-- `theme.toml` is this flavor's configuration file, in the format consistent with the [user's `theme.toml`](/docs/configuration/theme).
+- `flavor.toml` is this flavor's configuration file, in the format consistent with the [user's `theme.toml`](/docs/configuration/theme).
 - `tmtheme.xml` is a [tmTheme file](https://www.sublimetext.com/docs/color_schemes_tmtheme.html) that matches the colors of this flavor for code highlighting.
-- `screenshot.png` and `README.md` are the screenshot and the description of this flavor, respectively.
+- `README.md` and `screenshot.png` are the screenshot and the description of this flavor, respectively.
 - `LICENSE` and `LICENSE-tmtheme` are the licenses for the flavor and the `tmtheme.xml` file, respectively.
 
 ## Cooking a flavor
diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md
index aa7bb6b1..4f936b6a 100644
--- a/docs/plugins/overview.md
+++ b/docs/plugins/overview.md
@@ -21,20 +21,20 @@ You can extend Yazi's functionality through Lua plugins, which need to be placed
 └── yazi.toml
 ```
 
-Each plugin is a directory ending with `.yazi`, containing at least the following files:
+Each plugin is a directory with a hyphen-separated name, ending in `.yazi`, and containing at least the following files:
 
 ```
 bar.yazi/
 ├── init.lua
-├── LICENSE
-└── README.md
+├── README.md
+└── LICENSE
 ```
 
 Where:
 
 - `init.lua` is the entry point of this plugin.
-- `LICENSE` is the license file for this plugin.
 - `README.md` is the documentation of this plugin.
+- `LICENSE` is the license file for this plugin.
 
 ## Usage
 
@@ -80,14 +80,20 @@ This is because `init.lua` is commonly used to initialize plugin configurations,
 
 ```lua
 -- ~/.config/yazi/init.lua
-
--- Initialize the bar plugin
--- Which needs `~/.config/yazi/plugins/bar.yazi/init.lua` to export a `setup` function
-require("bar").setup {
+require("bar"):setup {
 	key1 = "value1",
 	key2 = "value2",
 	-- ...
 }
+
+-- ~/.config/yazi/plugins/bar.yazi/init.lua
+return {
+	setup(state, opts)
+		-- Save the user configuration to the plugin state
+		state.key1 = opts.key1
+		state.key2 = opts.key2
+	end,
+}
 ```
 
 ### Sync context
diff --git a/docs/resources.md b/docs/resources.md
index 0c115030..ebc6b84e 100644
--- a/docs/resources.md
+++ b/docs/resources.md
@@ -8,7 +8,7 @@ description: Some awesome plugins for Yazi.
 :::warning
 The plugin system is still in the early stage, and most of the plugins below only guarantee compatibility with the latest main branch of Yazi!
 
-Please make sure that both your Yazi and plugins are on the latest main branch to ensure proper functionality!
+Please make sure that both your Yazi and plugins are on the `HEAD` to ensure proper functionality!
 :::
 
 ## 🖼️ Previewers