From 232f31c6649e6348a5b0b64362f185f7f4db1dc0 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Sun, 21 Jun 2026 18:33:32 +0800
Subject: Add intro content and merge getting started page

---
 docs/README.md                         | 33 ++++++++++++++++
 docs/_sidebar.md                       |  3 +-
 docs/_zh_CN/README.md                  | 33 ++++++++++++++++
 docs/_zh_CN/_sidebar.md                |  3 +-
 docs/_zh_CN/pages/1-getting-started.md | 69 ++++++++++++++++++++++++++++++++++
 docs/_zh_CN/pages/1-intro.md           | 32 ----------------
 docs/_zh_CN/pages/2-getting-started.md | 62 ------------------------------
 docs/pages/1-getting-started.md        | 69 ++++++++++++++++++++++++++++++++++
 docs/pages/1-intro.md                  | 32 ----------------
 docs/pages/2-getting-started.md        | 62 ------------------------------
 10 files changed, 206 insertions(+), 192 deletions(-)
 create mode 100644 docs/_zh_CN/pages/1-getting-started.md
 delete mode 100644 docs/_zh_CN/pages/1-intro.md
 delete mode 100644 docs/_zh_CN/pages/2-getting-started.md
 create mode 100644 docs/pages/1-getting-started.md
 delete mode 100644 docs/pages/1-intro.md
 delete mode 100644 docs/pages/2-getting-started.md

(limited to 'docs')

diff --git a/docs/README.md b/docs/README.md
index 15c072e..4e327c3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,3 +3,36 @@
 <p align="center">
     This is documentation for the <b>Mingling</b> command-line framework, maintained by <a href="https://github.com/Weicao-CatilGrass">Weicao-CatilGrass</a>
 </p>
+
+## Intro
+
+If you're troubled by these issues —
+
+1. Too many subcommands make `main.rs` bloat rapidly;
+2. Handler logic mixed with side effects;
+3. Logging, auth, and other cross-cutting concerns are hard to inject non-invasively;
+4. Maintaining shell completion scripts for multiple platforms wears you out;
+5. Global resources everywhere, making testing difficult.
+
+… then you've come to the right place.
+
+Of course, if you're just curious about "how to write maintainable CLIs in Rust," you've also come to the right place — it'll be fun.
+
+## What is Mingling?
+
+> **Mìng Lìng** is the pinyin of the Chinese word **命令**,
+> which translates to **Command** in English.
+
+Mingling is a CLI framework built with Rust. It's free, open-source, and licensed under the permissive MIT / Apache 2.0 license.
+
+Mingling's design goals:
+
+- **Extensible**: From 3 subcommands to 30, same pattern, no framework swap
+- **Decoupled**: Parse args once, write business logic once, define output format once. Each independent.
+- **Type-driven**: Clear, typed data flows through the pipeline — not `Vec<String>`
+- **Lightweight deps**: Minimal core deps, low cost to pull in; advanced features on demand, no compile-time drag
+- **Efficient**: Dispatch logic generated at compile time, no unnecessary runtime overhead
+
+---
+
+Alright, wanna give it a try?
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index d60a631..47f46b8 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,6 +1,5 @@
 - [Welcome!](README)
-* [Introduction](pages/1-intro)
-* [Getting Started](pages/2-getting-started)
+* [Getting Started](pages/1-getting-started)
 * Other
   * [Features](pages/other/features)
   * [Naming Conventions](pages/other/naming_rule)
diff --git a/docs/_zh_CN/README.md b/docs/_zh_CN/README.md
index b302220..b529a86 100644
--- a/docs/_zh_CN/README.md
+++ b/docs/_zh_CN/README.md
@@ -3,3 +3,36 @@
 <p align="center">
     该页面为 <b>Mingling</b> 命令行框架的中文文档，由 <a href="https://github.com/Weicao-CatilGrass">Weicao-CatilGrass</a> 维护
 </p>
+
+## 前言
+
+如果你正被这些问题困扰——
+
+1. 子命令一多，`main.rs` 就迅速膨胀；
+2. Handler 中的逻辑与副作用混杂在一起；
+3. 日志、鉴权等横切关注点难以无侵入地插入；
+4. 为多个平台维护 shell 补全脚本令人心力交瘁；
+5. 全局资源到处都是，测试非常困难。
+
+…… 那么，你来对地方了。
+
+当然，如果只是对「怎么用 Rust 写出好维护的 CLI」这件事感兴趣，那你更来对地方了 —— 它会很有意思的。
+
+## 什么是 Mingling？
+
+> **Mìng Lìng** 是中文 **命令** 的汉语拼音，
+> 对应的英文单词是 **Command**。
+
+Mingling 是一个用 Rust 构建的 CLI 框架。它免费、开源，且使用宽松的 MIT / Apache 2.0 开源协议。
+
+Mingling 的设计目标：
+
+- **可扩展**：从 3 个子命令到 30 个，同一套模式，不换框架
+- **解耦**：参数解析写一次，业务逻辑写一次，输出格式写一次。各不相干
+- **类型驱动**：整个流水线上传递的是清晰、类型化的数据，而非 `Vec<String>`
+- **轻量依赖**：核心功能依赖少，引入负担低；按需启用高级特性，不拖慢编译
+- **高效**：编译期生成分发逻辑，运行时没有不必要的开销
+
+---
+
+好了，想来试试么？
diff --git a/docs/_zh_CN/_sidebar.md b/docs/_zh_CN/_sidebar.md
index 1fd2e13..620b11c 100644
--- a/docs/_zh_CN/_sidebar.md
+++ b/docs/_zh_CN/_sidebar.md
@@ -1,6 +1,5 @@
 - [Welcome!](README)
-* [介绍](pages/1-intro)
-* [起步](pages/2-getting-started)
+* [起步](pages/1-getting-started)
 * 其他
   * [特性](pages/other/features)
   * [命名规范](pages/other/naming_rule)
diff --git a/docs/_zh_CN/pages/1-getting-started.md b/docs/_zh_CN/pages/1-getting-started.md
new file mode 100644
index 0000000..2961464
--- /dev/null
+++ b/docs/_zh_CN/pages/1-getting-started.md
@@ -0,0 +1,69 @@
+<h1 align="center">起步</h1>
+
+## 创建一个新项目
+
+```bash
+cargo new my-cli
+cd my-cli
+```
+ 
+## 添加依赖
+
+在 `Cargo.toml` 写入如下内容
+
+```toml
+[dependencies.mingling]
+version = "0.2"
+features = []
+```
+ 
+## 启用特性
+
+**Mingling** 默认所有特性关闭，且不提供类似 `full` 的全开特性。
+
+因为部分特性会 **直接影响整个生命周期的行为**，需要你按需启用，例如：
+
+```toml
+[dependencies.mingling]
+version = "0.2"
+features = [
+    "parser",
+    "comp",
+]
+```
+ 
+> [!NOTE]
+> 请前往 [docs.rs](https://docs.rs/mingling/latest/mingling/feature/index.html) 或 [特性](pages/other/features) 以了解所有特性
+
+## 编写基本入口
+
+编写 `src/main.rs`，写入以下代码：
+
+```rust
+use mingling::prelude::*;
+ 
+fn main() {
+    let mut program = ThisProgram::new();
+ 
+    program.exec_and_exit();
+}
+ 
+gen_program!();
+```
+ 
+> [!IMPORTANT]
+> 文档中几乎所有 Rust 代码块都已在 CI 流程中编译通过，可以保证可用性。
+>
+> 但以 `// NOT VERIFIED` 开头的代码块 **未被验证**。
+>
+> 想确认哪些 `*.md` 文件被编译过？请看 [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml)
+
+## 编译验证
+
+```plaintext
+~# cargo check
+```
+ 
+---
+
+一切无误后，开始写点什么吧！
diff --git a/docs/_zh_CN/pages/1-intro.md b/docs/_zh_CN/pages/1-intro.md
deleted file mode 100644
index 7210d2e..0000000
--- a/docs/_zh_CN/pages/1-intro.md
+++ /dev/null
@@ -1,32 +0,0 @@
-<h1 align="center">介绍</h1>
-
-如果你正被这些问题困扰——
-
-1. 子命令一多，`main.rs` 就迅速膨胀；
-2. Handler 中的逻辑与副作用混杂在一起；
-3. 日志、鉴权等横切关注点难以无侵入地插入；
-4. 为多个平台维护 shell 补全脚本令人心力交瘁；
-5. 全局资源到处都是，测试非常困难。
-
-…… 那么，你来对地方了。
-
-当然，如果只是对「怎么用 Rust 写出好维护的 CLI」这件事感兴趣，那你更来对地方了 —— 它会很有意思的。
-
-## 什么是 Mingling？
-
-> **Mìng Lìng** 是中文 **命令** 的汉语拼音，
-> 对应的英文单词是 **Command**。
-
-Mingling 是一个用 Rust 构建的 CLI 框架。它免费、开源，且使用宽松的 MIT / Apache 2.0 开源协议。
-
-Mingling 的设计目标：
-
-- **可扩展**：从 3 个子命令到 30 个，同一套模式，不换框架
-- **解耦**：参数解析写一次，业务逻辑写一次，输出格式写一次。各不相干
-- **类型驱动**：整个流水线上传递的是清晰、类型化的数据，而非 `Vec<String>`
-- **轻量依赖**：核心功能依赖少，引入负担低；按需启用高级特性，不拖慢编译
-- **高效**：编译期生成分发逻辑，运行时没有不必要的开销
-
----
-
-好了，想来试试么？
diff --git a/docs/_zh_CN/pages/2-getting-started.md b/docs/_zh_CN/pages/2-getting-started.md
deleted file mode 100644
index 62eb94b..0000000
--- a/docs/_zh_CN/pages/2-getting-started.md
+++ /dev/null
@@ -1,62 +0,0 @@
-<h1 align="center">起步</h1>
-
-## 创建一个新项目
-
-```bash
-cargo new my-cli
-cd my-cli
-```
- 
-## 添加依赖
-
-在 `Cargo.toml` 写入如下内容
-
-```toml
-[dependencies.mingling]
-version = "0.2"
-features = []
-```
- 
-## 启用特性
-
-**Mingling** 默认所有特性关闭，且不提供类似 `full` 的全开特性。
-
-因为部分特性会 **直接影响整个生命周期的行为**，需要你按需启用，例如：
-
-```toml
-[dependencies.mingling]
-version = "0.2"
-features = [
-    "parser",
-    "comp",
-]
-```
- 
-> [!NOTE]
-> 请前往 [docs.rs](https://docs.rs/mingling/latest/mingling/feature/index.html) 或 [特性](pages/other/features) 以了解所有特性
-
-## 编写基本入口
-
-编写 `src/main.rs`，写入以下代码：
-
-```rust
-use mingling::prelude::*;
- 
-fn main() {
-    let mut program = ThisProgram::new();
-    
-    program.exec_and_exit();
-}
- 
-gen_program!();
-```
- 
-## 编译验证
-
-```plaintext
-~# cargo check
-```
- 
----
-
-一切无误后，开始写点什么吧！
diff --git a/docs/pages/1-getting-started.md b/docs/pages/1-getting-started.md
new file mode 100644
index 0000000..4832191
--- /dev/null
+++ b/docs/pages/1-getting-started.md
@@ -0,0 +1,69 @@
+<h1 align="center">Getting Started</h1>
+
+## Create a New Project
+
+```bash
+cargo new my-cli
+cd my-cli
+```
+ 
+## Add Dependency
+
+Add the following to `Cargo.toml`:
+
+```toml
+[dependencies.mingling]
+version = "0.2"
+features = []
+```
+ 
+## Enable Features
+
+**Mingling** has all features disabled by default and does not provide an all-in-one feature like `full`.
+
+Some features will **directly affect the behavior of the entire lifecycle**, so you need to enable them as needed, for example:
+
+```toml
+[dependencies.mingling]
+version = "0.2"
+features = [
+    "parser",
+    "comp",
+]
+```
+ 
+> [!NOTE]
+> Visit [docs.rs](https://docs.rs/mingling/latest/mingling/feature/index.html) or [Features](pages/other/features) to learn about all available features.
+
+## Write the Basic Entry Point
+
+Edit `src/main.rs` with the following code:
+
+```rust
+use mingling::prelude::*;
+ 
+fn main() {
+    let mut program = ThisProgram::new();
+ 
+    program.exec_and_exit();
+}
+ 
+gen_program!();
+```
+ 
+> [!IMPORTANT]
+> Almost all Rust code blocks in the documentation have been compiled through the CI pipeline and are guaranteed to be usable.
+>
+> However, code blocks starting with `// NOT VERIFIED` have **not been verified**.
+>
+> Want to know which `*.md` files have been compiled? Check [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml)
+
+## Verify Compilation
+
+```plaintext
+~# cargo check
+```
+ 
+---
+
+Once everything is good, start building!
diff --git a/docs/pages/1-intro.md b/docs/pages/1-intro.md
deleted file mode 100644
index edf83bb..0000000
--- a/docs/pages/1-intro.md
+++ /dev/null
@@ -1,32 +0,0 @@
-<h1 align="center">Introduction</h1>
-
-If you're troubled by these issues —
-
-1. Too many subcommands make `main.rs` bloat rapidly;
-2. Handler logic mixed with side effects;
-3. Logging, auth, and other cross-cutting concerns are hard to inject non-invasively;
-4. Maintaining shell completion scripts for multiple platforms wears you out;
-5. Global resources everywhere, making testing difficult.
-
-… then you've come to the right place.
-
-Of course, if you're just curious about "how to write maintainable CLIs in Rust," you've also come to the right place — it'll be fun.
-
-## What is Mingling?
-
-> **Mìng Lìng** is the pinyin of the Chinese word **命令**,
-> which translates to **Command** in English.
-
-Mingling is a CLI framework built with Rust. It's free, open-source, and licensed under the permissive MIT / Apache 2.0 license.
-
-Mingling's design goals:
-
-- **Extensible**: From 3 subcommands to 30, same pattern, no framework swap
-- **Decoupled**: Parse args once, write business logic once, define output format once. Each independent.
-- **Type-driven**: Clear, typed data flows through the pipeline — not `Vec<String>`
-- **Lightweight deps**: Minimal core deps, low cost to pull in; advanced features on demand, no compile-time drag
-- **Efficient**: Dispatch logic generated at compile time, no unnecessary runtime overhead
-
----
-
-Alright, wanna give it a try?
diff --git a/docs/pages/2-getting-started.md b/docs/pages/2-getting-started.md
deleted file mode 100644
index 35da464..0000000
--- a/docs/pages/2-getting-started.md
+++ /dev/null
@@ -1,62 +0,0 @@
-<h1 align="center">Getting Started</h1>
-
-## Create a New Project
-
-```bash
-cargo new my-cli
-cd my-cli
-```
- 
-## Add Dependency
-
-Add the following to `Cargo.toml`:
-
-```toml
-[dependencies.mingling]
-version = "0.2"
-features = []
-```
- 
-## Enable Features
-
-**Mingling** has all features disabled by default and does not provide an all-in-one feature like `full`.
-
-Some features will **directly affect the behavior of the entire lifecycle**, so you need to enable them as needed, for example:
-
-```toml
-[dependencies.mingling]
-version = "0.2"
-features = [
-    "parser",
-    "comp",
-]
-```
- 
-> [!NOTE]
-> Visit [docs.rs](https://docs.rs/mingling/latest/mingling/feature/index.html) or [Features](pages/other/features) to learn about all available features.
-
-## Write the Basic Entry Point
-
-Edit `src/main.rs` with the following code:
-
-```rust
-use mingling::prelude::*;
- 
-fn main() {
-    let mut program = ThisProgram::new();
- 
-    program.exec_and_exit();
-}
- 
-gen_program!();
-```
- 
-## Verify Compilation
-
-```plaintext
-~# cargo check
-```
- 
----
-
-Once everything is good, start building!
-- 
cgit