doc: configuration files

docs/configuration/index.md

@@ -36,4 +36,72 @@ $ sing-box check
 
 ```bash
 $ sing-box format -w
-```
+```
+
+### Multiple Configuration Files
+
+> You can skip this section if you are using only one configuration file.
+
+sing-box supports multiple files and multiple formats. The latter overwrites and merges into the former, in the order in which the configuration files are loaded.
+
+
+```bash
+# Load by the order of parameters
+sing-box run -c inbound.json -c outbound.yaml -c  -c http://url.to/config.toml
+# Load by the order of file names
+sing-box run -r -c config_dir
+```
+
+Suppose we have 2 `JSON` files:
+
+`a.json`:
+
+```json
+{
+  "log": {"level": "debug"},
+  "inbounds": [{"tag": "in-1"}],
+  "outbounds": [{"_priority": 100, "tag": "out-1"}],
+  "route": {"rules": [
+    {"_tag":"rule1","inbound":["in-1"],"outbound":"out-1"}
+  ]}
+}
+```
+
+`b.json`:
+
+```json
+{
+  "log": {"level": "error"},
+  "outbounds": [{"_priority": -100, "tag": "out-2"}],
+  "route": {"rules": [
+    {"_tag":"rule1","inbound":["in-1.1"],"outbound":"out-1.1"}
+  ]}
+}
+```
+
+Applied:
+
+```jsonc
+{
+  // level field is overwritten by the latter value
+  "log": {"level": "error"},
+  "inbounds": [{"tag": "in-1"}],
+  "outbounds": [
+    // Although out-2 is a latecomer, but it's in 
+    // the front due to the smaller "_priority"
+    {"tag": "out-2"},
+    {"tag": "out-1"}
+  ],
+  "route": {"rules": [
+    // 2 rules are merged into one due to the same "_tag",
+    // outbound field is overwritten during the merging
+    {"inbound":["in-1","in-1.1"],"outbound":"out-1.1"}
+  ]}
+}
+```
+
+Just remember these few rules:
+
+- Simple values (string, number, boolean) are overwritten, others (array, object) are merged.
+- Elements with same `_tag` in an array will be merged.
+- Elements in an array will be sorted by "_priority" field, the smaller the higher priority.

docs/configuration/index.zh.md

@@ -1,6 +1,6 @@
 # 引言
 
-sing-box 使用 JSON 作为配置文件格式。
+sing-box 支持 JSON、JSONC、YAML、TOML 作为配置文件格式。
 
 ### 结构
 
@@ -36,4 +36,73 @@ $ sing-box check
 
 ```bash
 $ sing-box format -w
-```
+```
+
+### 多个配置文件
+
+> 如果只使用单个配置文件，您完全可以忽略这一节。
+
+sing-box 支持多文件、多格式混合使用。按照配置文件的加载顺序，后者会覆盖并合并到前者。
+
+```bash
+# 根据参数顺序加载
+sing-box run -c inbound.json -c outbound.yaml -c http://url.to/config.toml
+```
+
+```bash
+# 根据文件名顺序加载
+sing-box run -r -c config_dir
+```
+
+多个配置文件是如何被加载的？假设我们有两个 `JSON` 文件：
+
+`a.json`:
+
+```json
+{
+  "log": {"level": "debug"},
+  "inbounds": [{"tag": "in-1"}],
+  "outbounds": [{"_priority": 100, "tag": "out-1"}],
+  "route": {"rules": [
+    {"_tag":"rule1","inbound":["in-1"],"outbound":"out-1"}
+  ]}
+}
+```
+
+`b.json`:
+
+```json
+{
+  "log": {"level": "error"},
+  "outbounds": [{"_priority": -100, "tag": "out-2"}],
+  "route": {"rules": [
+    {"_tag":"rule1","inbound":["in-1.1"],"outbound":"out-1.1"}
+  ]}
+}
+```
+
+合并后:
+
+```jsonc
+{
+  // level 字段被后来者覆盖
+  "log": {"level": "error"},
+  "inbounds": [{"tag": "in-1"}],
+  "outbounds": [
+    // out-2 虽然是后来者，但由于 _priority 小，反而排在前面
+    {"tag": "out-2"}, 
+    {"tag": "out-1"}
+  ],
+  "route": {"rules": [
+    // 2条规则被合并，因为它们具有相同的 "_tag"，
+    // outbound 字段在合并过程被覆盖为 "out-1.1"
+    {"inbound":["in-1","in-1.1"],"outbound":"out-1.1"}
+  ]}
+}
+```
+
+只需记住这几个规则：
+
+- 简单字段（字符串、数字、布尔值）会被后来者覆盖，其它字段（数组、对象）会被合并。
+- 数组内拥有相同 `_tag` 的对象会被合并。
+- 数组会按 `_priority` 字段值进行排序，越小的优先级越高。