Feature docs

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+name: Deploy docs to github pages
+on:
+  push:
+    branches: [main, feature-docs]
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+      - name: Install dependencies
+        run: |
+          cd docs
+          pnpm install --frozen-lockfile
+      - name: Build website
+        run: |
+          cd docs
+          pnpm build
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/config/basic.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 1
+---
+
+# 基本概念
+
+Rabbit Digger Pro 的配置主要由两部分组成:
+
+- `net`: 虚拟网络层，可以是:
+
+  - 本地网络
+  - 代理网络
+  - 规则路由
+  - 其他特殊类型
+
+- `server`: 代理服务器，支持:
+  - HTTP 服务器
+  - SOCKS5 服务器
+  - 混合模式服务器
+
+## 工作原理
+
+```mermaid
+graph LR;
+    Server(代理服务器) -->|使用| Rule(规则路由)
+    Rule -->|分流| Proxy1(代理1)
+    Rule -->|分流| Proxy2(代理2)
+    Rule -->|分流| Direct(直连)
+    Proxy1 --> Internet(互联网)
+    Proxy2 --> Internet
+    Direct --> Internet
+```
+
+要点:
+
+1. 每个 net 都有唯一的名字和类型
+2. 大多数 net 可以链式组合
+3. server 可以同时部署多个
+4. 支持灵活的规则分流
+
+详细配置示例请参考[配置指南](format)。

docs/docs/config/format.md

@@ -0,0 +1,109 @@
+---
+sidebar_position: 2
+---
+
+# 配置文件格式
+
+`rabbit-digger-pro` 使用 YAML 格式的配置文件。配置文件由三个主要的根级字段组成：
+
+## net
+
+`net` 字段用于配置代理节点和链路。每个代理节点都是一个键值对，其中键是节点名称，值是节点配置。
+
+```yaml
+net:
+  # Shadowsocks 代理节点
+  my_ss:
+    type: shadowsocks
+    server: example.com:1234
+    cipher: aes-256-cfb
+    password: password
+
+  # HTTP 代理节点
+  http_proxy:
+    type: http
+    server: 127.0.0.1
+    port: 8080
+```
+
+## server
+
+`server` 字段用于配置本地服务器，比如 HTTP/SOCKS5 代理服务器。
+
+```yaml
+server:
+  # 混合模式代理服务器
+  mixed:
+    type: http+socks5
+    bind: 127.0.0.1:1080
+    net: my_ss # 使用上面定义的 my_ss 节点
+
+  # HTTP 代理服务器
+  http:
+    type: http
+    bind: 127.0.0.1:8080
+    net: local # 使用直连节点
+```
+
+## import
+
+`import` 字段用于导入其他配置文件或 Clash 配置。rabbit-digger-pro 会根据 `import` 的顺序依次导入配置文件。
+
+```yaml
+import:
+  # 导入本地配置文件，合并到当前配置
+  - type: merge
+    source:
+      path: ./local-config.yaml
+
+  # 导入 Clash 配置
+  - type: clash
+    source:
+      poll:
+        url: "https://example.com/clash-config.yaml"
+        interval: 86400
+```
+
+### 完整示例
+
+```yaml
+net:
+  # Shadowsocks 代理节点
+  my_ss:
+    type: shadowsocks
+    server: example.com:1234
+    cipher: aes-256-cfb
+    password: password
+
+  # HTTP 代理节点
+  http_proxy:
+    type: http
+    server: 127.0.0.1
+    port: 8080
+
+server:
+  # 混合模式代理服务器
+  mixed:
+    type: http+socks5
+    bind: 127.0.0.1:1080
+    net: my_ss # 使用上面定义的 my_ss 节点
+
+  # HTTP 代理服务器
+  http:
+    type: http
+    bind: 127.0.0.1:8080
+    net: local # 使用直连节点
+
+import:
+  # 导入本地配置文件，合并到当前配置
+  - type: merge
+    source:
+      path: ./local-config.yaml
+
+  # 导入 Clash 配置
+  - type: clash
+    source:
+      poll:
+        url: "https://example.com/clash-config.yaml"
+        interval: 86400
+```

docs/docs/inside/README.md

@@ -0,0 +1,42 @@
+---
+sidebar: auto
+---
+
+# Inside
+
+`rabbit-digger` 内部的秘密 🐰...
+
+## Net
+
+`Net` 是 `rabbit-digger` 的核心概念. 每个代理协议都是根据一个配置(如代理服务器地址, 认证方式, 基于的 `Net`) 构造一个新的 `Net`. 这个 `Net` 提供了 `tcp_connect` 和 `udp_bind`, 对使用者隐藏了服务器的连接细节, 能够让使用者直接调用 `tcp_connect` 和 `udp_bind`.
+
+`Net` 的实现者不应该使用异步运行时提供的 `TcpStream` 和 `UdpSocket` 来连接代理服务器. 而是应该在 `Config` 中声明 `NetRef`, 然后使用这个 `Net` 来连接代理服务器.
+
+因此, 每个代理协议都能够互相嵌套, 自然的实现了代理链.
+
+## NetRef
+
+`NetRef` 是一个 `enum`, 有 `String` 和 `Net` 两种状态. 当 `Config` 从文件读入时, `NetRef` 是一个未解析的字符串. 而 `rabbit-digger` 会根据引用关系一次将 `NetRef` 解析成 `Net` 实例, 然后传给 `NetFactory::new`.
+
+## ExternalFile
+
+`ExternalFile` 可用在 `Config` 中. 代表着这个字段是一个外部的文件. `ExternalFile` 可以是文件, 也可以是 `Url`. 当 `ExternalFile` 是文件且 `watch` 为 `true` 时, `Net` 会在文件变更时被重建. 当 `Url` 和 `interval` 被设置时, 文件会被轮询, 并且在改变时重建 `Net`.
+
+## Config 处理流
+
+所有 `Config` 类型都实现了 `Config` trait, `rabbit-digger` 会在加载 `Net` 时调用 `Config::visit` 来访问内部的字段, 并填入所有的 `NetRef`, `ExternalFile`. 在填入 `ExternalFile` 的时候会记录所有使用到的文件, 并在文件变动的时候重新构建 `Net`.
+
+```mermaid
+flowchart TD
+    input(Config.yml)
+    mkctx[创建配置上下文, 用于保存 Config 依赖的文件]
+    import[处理 Import 字段]
+    build[构造 Net 和 Server]
+    cond{依赖的文件
+    是否改变?}
+    run_server[运行 Server]
+
+    input --> mkctx --> import --> build --> run_server --> cond
+    cond --> |Yes| mkctx
+    cond --> |No| run_server
+```

docs/docs/tutorial-basics/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Tutorial - Basics",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "5 minutes to learn the most important Docusaurus concepts."
+  }
+}