docs: add flavors documentation

docs/configuration/theme.md

@@ -218,6 +218,10 @@ prepend_rules = [
 
 	# Icon with a color
 	{ name = "*.lua", text = "", fg = "#51a0cf" },
+
+	# You can also use `is` rule, just like `[filetype]` section
+	# Orphan symbolic links
+	{ name = "*", is = "orphan", text = "" },
 ]
 
 append_rules = [

docs/faq.md

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

docs/flavors/_category_.json

@@ -0,0 +1,8 @@
+{
+	"label": "Flavors (WIP)",
+	"position": 6,
+	"link": {
+		"type": "doc",
+		"id": "flavors/overview"
+	}
+}

docs/flavors/overview.md

@@ -0,0 +1,53 @@
+---
+id: overview
+sidebar_position: 0
+sidebar_label: Flavors (WIP)
+description: Learn how to use Yazi flavors.
+---
+
+# Flavors (WIP)
+
+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.
+
+## Directory structure
+
+These flavors are placed in the `flavors` subdirectory of the Yazi configuration directory, so either:
+
+- `~/.config/yazi/flavors/` on Unix-like systems.
+- `C:\Users\USERNAME\AppData\Roaming\yazi\config\flavors\` on Windows.
+
+```
+~/.config/yazi/
+├── flavors/
+│   ├── foo.yazi/
+│   └── bar.yazi/
+└── theme.toml
+```
+
+Each flavor is a directory ending with `.yazi`, containing `theme.toml` and `tmtheme.xml` files. For instance, the structure of the `bar` flavor is as:
+
+```
+bar.yazi/
+├── LICENSE
+├── LICENSE-tmtheme
+├── README.md
+├── screenshot.png
+├── theme.toml
+└── tmtheme.xml
+```
+
+Where:
+
+- `LICENSE` and `LICENSE-tmtheme` are the licenses of the flavor and the `tmtheme.xml` file, respectively.
+- `README.md` and `screenshot.png` are the description and the screenshot of the flavor, respectively.
+- `theme.toml` is the flavor's configuration file in the format consistent with the [user's `theme.toml`](/docs/configuration/theme).
+- `tmtheme.xml` is a thTheme file that matches the colors of this flavor for code highlighting.
+
+## Cooking a flavor
+
+Please use our [flavor-template](https://github.com/yazi-rs/flavor-template) repository as a starting point to create your own flavor.

docs/plugins/overview.md

@@ -1,7 +1,7 @@
 ---
 id: overview
 sidebar_position: 0
-sidebar_label: Plugin
+sidebar_label: Plugins (BETA)
 description: Learn how to extend Yazi with Lua plugins.
 ---
 

docs/resources.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 description: Some awesome plugins for Yazi.
 ---
 
@@ -48,3 +48,12 @@ Audio:
 ## Shell plugins
 
 - [yazi-prompt.sh](https://github.com/Sonico98/yazi-prompt.sh) - Display an indicator in your prompt when running inside a yazi subshell.
+
+## Add yours
+
+We are so happy to add your plugin/flavor to this page!
+
+If your plugin/flavor meets the following requirements, please click `Edit this page` below to add it:
+
+- **Functional** - we will install and test it, since we want all links included on this page to be valid. If it's available only on a specific platform, a note should be added in the README.
+- **Follow conventions** - it should be a directory/repository ending with `.yazi`, and include the files listed in the [plugin documentation](/docs/plugins/overview) or [flavor documentation](/docs/flavors/overview).

docs/tips.md

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