From 8eff052229fba82fa86e351850217a3ca4f2afac Mon Sep 17 00:00:00 2001
From: sxyazi <sxyazi@gmail.com>
Date: Mon, 26 Feb 2024 10:24:49 +0800
Subject: [PATCH] docs: add flavors documentation

---
 docs/configuration/theme.md  |  4 +++
 docs/faq.md                  |  2 +-
 docs/flavors/_category_.json |  8 ++++++
 docs/flavors/overview.md     | 53 ++++++++++++++++++++++++++++++++++++
 docs/plugins/overview.md     |  2 +-
 docs/resources.md            | 11 +++++++-
 docs/tips.md                 |  2 +-
 7 files changed, 78 insertions(+), 4 deletions(-)
 create mode 100644 docs/flavors/_category_.json
 create mode 100644 docs/flavors/overview.md

diff --git a/docs/configuration/theme.md b/docs/configuration/theme.md
index 30ce25e0..b651b8a4 100644
--- a/docs/configuration/theme.md
+++ b/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 = [
diff --git a/docs/faq.md b/docs/faq.md
index be7699ca..671e0e9e 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 description: Answers to some frequently asked questions about Yazi.
 ---
 
diff --git a/docs/flavors/_category_.json b/docs/flavors/_category_.json
new file mode 100644
index 00000000..14f1aca2
--- /dev/null
+++ b/docs/flavors/_category_.json
@@ -0,0 +1,8 @@
+{
+	"label": "Flavors (WIP)",
+	"position": 6,
+	"link": {
+		"type": "doc",
+		"id": "flavors/overview"
+	}
+}
diff --git a/docs/flavors/overview.md b/docs/flavors/overview.md
new file mode 100644
index 00000000..ebce62f6
--- /dev/null
+++ b/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.
diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md
index 560c1035..4cd14514 100644
--- a/docs/plugins/overview.md
+++ b/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.
 ---
 
diff --git a/docs/resources.md b/docs/resources.md
index eb27aca2..ac7fe88c 100644
--- a/docs/resources.md
+++ b/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).
diff --git a/docs/tips.md b/docs/tips.md
index 5901786a..ba9bc38b 100644
--- a/docs/tips.md
+++ b/docs/tips.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 description: A few helpful tips for using Yazi.
 ---