3 files changed, 204 insertions, 0 deletions
diff --git a/docs/_zh_CN/pages/advanced/.name b/docs/_zh_CN/pages/advanced/.name
new file mode 100644
index 0000000..eb92a2d
--- /dev/null
+++ b/docs/_zh_CN/pages/advanced/.name
@@ -0,0 +1 @@
+进阶
diff --git a/docs/_zh_CN/pages/advanced/1-completion.md b/docs/_zh_CN/pages/advanced/1-completion.md
new file mode 100644
index 0000000..3941404
--- /dev/null
+++ b/docs/_zh_CN/pages/advanced/1-completion.md
@@ -0,0 +1,83 @@
+<h1 align="center">补全</h1>
+<p align="center">
+    使用 comp 特性实现完全动态的补全系统
+</p>
+
+Mingling 的补全是**完全动态**的——没有静态的补全文件，而是在运行时根据用户当前输入实时计算补全建议。
+
+## 开启 comp
+
+```toml
+# Cargo.toml
+[dependencies.mingling]
+features = ["comp"]
+ 
+[build-dependencies.mingling]
+features = [
+    "comp",
+    # 启用 `builds` 特性以提供构建期支持
+    "builds"
+]
+```
+ 
+## 工作原理
+
+当用户按下 `TAB` 时，补全脚本会调用程序的隐藏子命令 `__comp`，它会根据输入的 `ShellContext` 动态地查询最合适的建议。
+
+这个隐藏子命令由 `gen_program!()` 在启用 `comp` 特性时自动生成，对应的分发器是 `CMDCompletion`，你需要使用 `with_dispatcher` 添加到程序中。
+
+补全流程：
+
+1. 二次匹配用户当前输入的 `Dispatcher`
+2. 调用对应的 `#[completion]` 函数
+3. 函数返回 `Suggest`（文件补全或建议列表）
+4. 通知 Shell 将建议呈现出来
+
+## 定义补全
+
+用 `#[completion(EntryType)]` 为 Entry 定义补全逻辑：
+
+```rust
+// Features: ["comp"]
+@@@use mingling::prelude::*;
+@@@use mingling::{ShellContext, Suggest, SuggestItem};
+@@@use std::collections::BTreeSet;
+@@@dispatcher!("greet", CMDGreet => EntryGreet);
+ 
+#[completion(EntryGreet)]
+fn complete_greet(ctx: &ShellContext) -> Suggest {
+    if ctx.previous_word == "greet" {
+        let mut items = BTreeSet::new();
+        items.insert(SuggestItem::new_with_desc("Alice".into(), "Likes to receive messages".into()));
+        items.insert(SuggestItem::new("World".into()));
+        Suggest::Suggest(items)
+    } else {
+        Suggest::FileCompletion
+    }
+}
+```
+ 
+`suggest!` 宏是更简洁的写法，效果相同：
+
+```rust
+// Features: ["comp"]
+@@@use mingling::macros::suggest;
+@@@fn example() {
+suggest! {
+    "Alice": "Likes to receive messages",
+    "World"
+};
+@@@}
+```
+ 
+`ShellContext` 包含用户当前的输入状态（`previous_word`、`current_word`、`all_words` 等），`Suggest` 有两种变体：`Suggest::Suggest(list)` 返回建议列表，`Suggest::FileCompletion` 交给 shell 自己做文件补全。
+
+## 生成补全脚本
+
+在 `build.rs` 中调用 `build_comp_scripts` 生成补全脚本（需要 `builds` + `comp` 特性）。
+
+详见 [example-completion](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion)。
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>
diff --git a/docs/_zh_CN/pages/advanced/2-structural-renderer.md b/docs/_zh_CN/pages/advanced/2-structural-renderer.md
new file mode 100644
index 0000000..14164da
--- /dev/null
+++ b/docs/_zh_CN/pages/advanced/2-structural-renderer.md
@@ -0,0 +1,120 @@
+<h1 align="center">结构化渲染</h1>
+<p align="center">
+    使用 structural_renderer 特性将结果渲染为序列化文本
+</p>
+
+启用 `structural_renderer` 后，你的程序可以通过 `--json`、`--yaml` 等参数将输出切换为结构化格式，方便与其他工具集成。
+
+## 开启特性
+
+```toml
+[dependencies.mingling]
+features = ["structural_renderer"]
+```
+ 
+`structural_renderer` 会自动启用 `json_serde_fmt`。
+
+如果需要更多格式，可以启用 `structural_renderer_full`（包含 JSON、YAML、TOML、RON）。
+
+> [!NOTE]
+> 若需要定制输出类型，可以查看 [特性](./pages/other/features)
+
+## 基本用法
+
+启用 `StructuralRendererSetup` 后，用 `pack_structural!` 替代 `pack!` 来声明支持结构化输出的类型：
+
+```rust
+// Features: ["structural_renderer"]
+// Dependencies:
+// serde = "1"
+@@@use mingling::setup::StructuralRendererSetup;
+@@@dispatcher!("render", CMDRender => EntryRender);
+ 
+// pack_structural! 等价于 pack! + StructuralData
+pack_structural!(ResultInfo = (String, i32));
+ 
+#[chain]
+fn handle_render(args: EntryRender) -> Next {
+    let name = args.inner.first().cloned().unwrap_or_default();
+    let age = args.inner.get(1).and_then(|s| s.parse().ok()).unwrap_or(0);
+    ResultInfo::new((name, age))
+}
+ 
+#[renderer]
+fn render_info(r: ResultInfo) {
+    r_println!("{:?}", *r);
+}
+```
+ 
+运行效果：
+
+```text
+~# my-cli render Bob 22
+("Bob", 22)
+ 
+~# my-cli render Bob 22 --json
+{"inner":["Bob",22]}
+```
+ 
+用户传入 `--json` 时，框架自动将渲染结果序列化为 JSON，无需修改业务代码。
+
+## 自定义输出结构
+
+`pack_structural!` 的默认输出包含 `inner` 字段。要完全控制输出结构，可以用 `#[derive(StructuralData, Serialize, Groupped)]` 手动定义类型：
+
+```rust
+// Features: ["structural_renderer"]
+// Dependencies:
+// serde = "1"
+@@@use mingling::prelude::*;
+@@@use mingling::setup::StructuralRendererSetup;
+@@@use mingling::StructuralData;
+@@@use serde::Serialize;
+@@@dispatcher!("render", CMDRender => EntryRender);
+ 
+#[derive(Serialize, StructuralData, Groupped)]
+struct Info {
+    name: String,
+    age: i32,
+}
+ 
+#[chain]
+fn handle_render(args: EntryRender) -> Next {
+    let name = args.inner.first().cloned().unwrap_or_default();
+    let age = args.inner.get(1).and_then(|s| s.parse().ok()).unwrap_or(0);
+    Info { name, age }.to_render()
+}
+ 
+#[renderer]
+fn render_info(info: Info) {
+    r_println!("{} is {} years old", info.name, info.age);
+}
+@@@
+@@@fn main() {
+@@@    let mut program = ThisProgram::new();
+@@@    program.with_setup(StructuralRendererSetup);
+@@@    program.with_dispatcher(CMDRender);
+@@@    program.exec();
+@@@}
+@@@gen_program!();
+```
+ 
+这时 `--json` 输出：
+
+```json
+{ "name": "Bob", "age": 22 }
+```
+ 
+## 注意事项
+
+- 支持格式：JSON、YAML、TOML、RON（取决于启用的特性）
+- `StructuralRendererSetup` 注册 `--json`、`--yaml`、`--toml`、`--ron` 等全局参数
+
+> [!NOTE]
+> 每个类型仍需一个**空的 Renderer**，否则该类型 **不被视为可渲染**
+
+详见 [example-structural-renderer](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-structural-renderer)。
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>