documentation: Refactor docs

SagerNet · Nov 16, 2023 · 8e9d6c4 · 8e9d6c4
1 parent 7848291
commit 8e9d6c4
Show file tree

Hide file tree

Showing 83 changed files with 1,511 additions and 1,716 deletions.
diff --git a/Makefile b/Makefile
@@ -14,7 +14,7 @@ MAIN_PARAMS = $(PARAMS) -tags $(TAGS)
 MAIN = ./cmd/sing-box
 PREFIX ?= $(shell go env GOPATH)
 
-.PHONY: test release
+.PHONY: test release docs
 
 build:
 	go build $(MAIN_PARAMS) $(MAIN)
@@ -182,6 +182,14 @@ lib_install:
 	go install -v github.com/sagernet/gomobile/cmd/[email protected]
 	go install -v github.com/sagernet/gomobile/cmd/[email protected]
 
+docs:
+	mkdocs serve
+
+publish_docs:
+	mkdocs gh-deploy -m "Update" --force --ignore-version --no-history
+
+docs_install:
+	pip install --force-reinstall mkdocs-material=="9.*" mkdocs-static-i18n=="1.2.*"
 clean:
 	rm -rf bin dist sing-box
 	rm -f $(shell go env GOPATH)/sing-box

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,3 +1,5 @@
+# :material-alert-decagram: ChangeLog
+
 #### 1.6.5
 
 * Fix crash if TUIC inbound authentication failed

diff --git a/docs/clients/android/features.md b/docs/clients/android/features.md
@@ -0,0 +1,54 @@
+# :material-decagram: Features
+
+#### UI options
+
+* Display realtime network speed in the notification
+
+#### Service
+
+SFA allows you to run sing-box through ForegroundService or VpnService (when TUN is required).
+
+#### TUN
+
+SFA provides an unprivileged TUN implementation through Android VpnService.
+
+| TUN inbound option            | Available | Note               |
+|-------------------------------|-----------|--------------------|
+| `interface_name`              | ✖️        | Managed by Android |
+| `inet4_address`               | ✔️        | /                  |
+| `inet6_address`               | ✔️        | /                  |
+| `mtu`                         | ✔️        | /                  |
+| `auto_route`                  | ✔️        | /                  |
+| `strict_route`                | ✖️        | Not implemented    |
+| `inet4_route_address`         | ✔️        | /                  |
+| `inet6_route_address`         | ✔️        | /                  |
+| `inet4_route_exclude_address` | ✔️        | /                  |
+| `inet6_route_exclude_address` | ✔️        | /                  |
+| `endpoint_independent_nat`    | ✔️        | /                  |
+| `stack`                       | ✔️        | /                  |
+| `include_interface`           | ✖️        | No permission      |
+| `exclude_interface`           | ✖️        | No permission      |
+| `include_uid`                 | ✖️        | No permission      |
+| `exclude_uid`                 | ✖️        | No permission      |
+| `include_android_user`        | ✖️        | No permission      |
+| `include_package`             | ✔️        | /                  |
+| `exclude_package`             | ✔️        | /                  |
+| `platform`                    | ✔️        | /                  |
+
+### Override
+
+Overrides profile configuration items with platform-specific values.
+
+#### Per-app proxy
+
+SFA allows you to select a list of Android apps that require proxying or bypassing in the graphical interface to
+override the `include_package` and `exclude_package` configuration items.
+
+In particular, the selector also provides the “China apps” scanning feature, providing Chinese users with an excellent
+experience to bypass apps that do not require a proxy. Specifically, by scanning China application or SDK
+characteristics through dex class path and other means, there will be almost no missed reports.
+
+### Chore
+
+* The working directory is located at `/sdcard/Android/data/io.nekohasekai.sfa/files` (External files directory)
+* Crash logs is located in `$working_directory/stderr.log`
diff --git a/docs/clients/android/index.md b/docs/clients/android/index.md
@@ -0,0 +1,18 @@
+# :material-android: sing-box for Android
+
+SFA allows users to manage and run local or remote sing-box configuration files, and provides
+platform-specific function implementation, such as TUN transparent proxy implementation.
+
+## :material-graph: Requirements
+
+* Android 5.0+
+
+## :material-download: Download
+
+* [Play Store](https://play.google.com/store/apps/details?id=io.nekohasekai.sfa)
+* [Play Store (Beta)](https://play.google.com/apps/testing/io.nekohasekai.sfa)
+* [Github Releases](https://github.com/SagerNet/sing-box/releases)
+
+## :material-source-repository: Source code
+
+* [Github](https://github.com/SagerNet/sing-box-for-android)
diff --git a/docs/clients/apple/features.md b/docs/clients/apple/features.md
@@ -0,0 +1,42 @@
+# :material-decagram: Features
+
+#### UI options
+
+* Always On
+* Include All Networks (Proxy traffic for LAN and cellular services)
+* (Apple tvOS) Import profile from iPhone/iPad
+
+#### Service
+
+SFI/SFM/SFT allows you to run sing-box through NetworkExtension with Application Extension or System Extension.
+
+#### TUN
+
+SFI/SFM/SFT provides an unprivileged TUN implementation through NetworkExtension.
+
+| TUN inbound option            | Available | Note              |
+|-------------------------------|-----------|-------------------|
+| `interface_name`              | ✖️        | Managed by Darwin |
+| `inet4_address`               | ✔️        | /                 |
+| `inet6_address`               | ✔️        | /                 |
+| `mtu`                         | ✔️        | /                 |
+| `auto_route`                  | ✔️        | /                 |
+| `strict_route`                | ✖️        | Not implemented   |
+| `inet4_route_address`         | ✔️        | /                 |
+| `inet6_route_address`         | ✔️        | /                 |
+| `inet4_route_exclude_address` | ✔️        | /                 |
+| `inet6_route_exclude_address` | ✔️        | /                 |
+| `endpoint_independent_nat`    | ✔️        | /                 |
+| `stack`                       | ✔️        | /                 |
+| `include_interface`           | ✖️        | Not implemented   |
+| `exclude_interface`           | ✖️        | Not implemented   |
+| `include_uid`                 | ✖️        | Not implemented   |
+| `exclude_uid`                 | ✖️        | Not implemented   |
+| `include_android_user`        | ✖️        | Not implemented   |
+| `include_package`             | ✖️        | Not implemented   |
+| `exclude_package`             | ✖️        | Not implemented   |
+| `platform`                    | ✔️        | /                 |
+
+### Chore
+
+* Crash logs is located in `Settings` -> `View Service Log`
diff --git a/docs/clients/apple/index.md b/docs/clients/apple/index.md
@@ -0,0 +1,18 @@
+# :material-apple: sing-box for Apple platforms
+
+SFI/SFM/SFT allows users to manage and run local or remote sing-box configuration files, and provides
+platform-specific function implementation, such as TUN transparent proxy implementation.
+
+## :material-graph: Requirements
+
+* iOS 15.0+ / macOS 13.0+ / Apple tvOS 17.0+
+* An Apple account outside of mainland China
+
+## :material-download: Download
+
+* [AppStore](https://apps.apple.com/us/app/sing-box/id6451272673)
+* [TestFlight (Beta)](https://testflight.apple.com/join/AcqO44FH)
+
+## :material-source-repository: Source code
+
+* [Github](https://github.com/SagerNet/sing-box-for-apple)
diff --git a/docs/clients/general.md b/docs/clients/general.md
@@ -0,0 +1,59 @@
+# :material-pencil-ruler: General
+
+Describes and explains the functions implemented uniformly by sing-box graphical clients.
+
+### Profile
+
+Profile describes a sing-box configuration file and its state.
+
+#### Local
+
+* Local Profile represents a local sing-box configuration with minimal state
+* The graphical client must provide an editor to modify configuration content
+
+#### iCloud (on iOS and macOS)
+
+* iCloud Profile represents a remote sing-box configuration with iCloud as the update source
+* The configuration file is stored in the sing-box folder under iCloud
+* The graphical client must provide an editor to modify configuration content
+
+#### Remote
+
+* Remote Profile represents a remote sing-box configuration with a URL as the update source.
+* The graphical client should provide a configuration content viewer
+* The graphical client must implement automatic profile update (default interval is 60 minutes) and HTTP Basic
+  authorization.
+
+At the same time, the graphical client must provide support for importing remote profiles
+through a specific URL Scheme. The URL is defined as follows:
+
+```
+sing-box://import-remote-profile?url=urlEncodedURL#urlEncodedName
+```
+
+### Dashboard
+
+While the sing-box service is running, the graphical client should provide a Dashboard interface to manage the service.
+
+#### Status
+
+Dashboard should display status information such as memory, connection, and traffic.
+
+#### Mode
+
+Dashboard should provide a Mode selector for switching when the configuration uses at least two `clash_mode` values.
+
+#### Groups
+
+When the configuration includes group outbounds (specifically, Selector or URLTest),
+the dashboard should provide a Group selector for status display or switching.
+
+### Chore
+
+#### Core
+
+Graphical clients should provide a Core region:
+
+* Display the current sing-box version
+* Provides a button to clean the working directory
+* Provides a memory limiter switch
diff --git a/docs/clients/index.md b/docs/clients/index.md
@@ -0,0 +1,13 @@
+# :material-cellphone-link: Graphical Clients
+
+Maintained by Project S to provide a unified experience and platform-specific functionality.
+
+| Platform                              | Client                                  |
+|---------------------------------------|-----------------------------------------|
+| :material-android: Android            | [sing-box for Android](./android)       |
+| :material-apple: iOS/macOS/Apple tvOS | [sing-box for Apple platforms](./apple) |
+| TODO                                  | /                                       |
+
+Some third-party projects that claim to use sing-box or use sing-box as a selling point are not listed here. The core
+motivation of the maintainers of such projects is to acquire more users, and even though they provide friendly VPN
+client features, the code is usually of poor quality and contains ads.
diff --git a/docs/clients/index.zh.md b/docs/clients/index.zh.md
@@ -0,0 +1,12 @@
+# :material-cellphone-link: 图形界面客户端
+
+由 Project S 维护，提供统一的体验与平台特定的功能。
+
+| 平台                                    | 客户端                                     |
+|---------------------------------------|-----------------------------------------|
+| :material-android: Android            | [sing-box for Android](./android)       |
+| :material-apple: iOS/macOS/Apple tvOS | [sing-box for Apple platforms](./apple) |
+| TODO                                  | /                                       |
+
+此处没有列出一些声称使用或以 sing-box 为卖点的第三方项目。此类项目维护者的动机是获得更多用户，即使它们提供友好的商业
+VPN 客户端功能， 但代码质量很差且包含广告。
diff --git a/docs/clients/privacy.md b/docs/clients/privacy.md
@@ -0,0 +1,4 @@
+# :material-security: Privacy policy
+
+sing-box and official graphics clients do not collect or share personal data,
+and the data generated by the software is always on your device.
diff --git a/docs/configuration/dns/server.md b/docs/configuration/dns/server.md
@@ -49,15 +49,15 @@ The address of the dns server.
 
 !!! warning ""
 
-    QUIC and HTTP3 transport is not included by default, see [Installation](/#installation).
+    QUIC and HTTP3 transport is not included by default, see [Installation](./#installation).
 
 !!! info ""
 
     the RCode transport is often used to block queries. Use with rules and the `disable_cache` rule option.
 
 !!! warning ""
 
-    DHCP transport is not included by default, see [Installation](/#installation).
+    DHCP transport is not included by default, see [Installation](./#installation).
 
 | RCode             | Description           | 
 |-------------------|-----------------------|

diff --git a/docs/configuration/experimental/index.md b/docs/configuration/experimental/index.md
@@ -46,7 +46,7 @@
 
 !!! error ""
 
-    Clash API is not included by default, see [Installation](/#installation).
+    Clash API is not included by default, see [Installation](./#installation).
 
 #### external_controller
 
@@ -112,7 +112,7 @@ If not empty, `store_selected` will use a separate store keyed by it.
 
 !!! error ""
 
-    V2Ray API is not included by default, see [Installation](/#installation).
+    V2Ray API is not included by default, see [Installation](./#installation).
 
 #### listen
 

diff --git a/docs/configuration/inbound/hysteria.md b/docs/configuration/inbound/hysteria.md
@@ -31,7 +31,7 @@
 
 !!! warning ""
 
-    QUIC, which is required by hysteria is not included by default, see [Installation](/#installation).
+    QUIC, which is required by hysteria is not included by default, see [Installation](./#installation).
 
 ### Listen Fields
 

diff --git a/docs/configuration/inbound/hysteria2.md b/docs/configuration/inbound/hysteria2.md
@@ -4,8 +4,8 @@
 {
   "type": "hysteria2",
   "tag": "hy2-in",
-
-  ... // Listen Fields
+  ...
+  // Listen Fields
 
   "up_mbps": 100,
   "down_mbps": 100,
@@ -28,7 +28,14 @@
 
 !!! warning ""
 
-    QUIC, which is required by Hysteria2 is not included by default, see [Installation](/#installation).
+    QUIC, which is required by Hysteria2 is not included by default, see [Installation](./#installation).
+
+!!! warning "Difference from official Hysteria2"
+
+    The official program supports an authentication method called **userpass**,
+    which essentially uses a combination of `<username>:<password>` as the actual password,
+    while sing-box does not provide this alias.
+    To use sing-box with the official program, you need to fill in that combination as the actual password.
 
 ### Listen Fields
 

diff --git a/docs/configuration/inbound/hysteria2.zh.md b/docs/configuration/inbound/hysteria2.zh.md
@@ -4,8 +4,8 @@
 {
   "type": "hysteria2",
   "tag": "hy2-in",
-
-  ... // 监听字段
+  ...
+  // 监听字段
 
   "up_mbps": 100,
   "down_mbps": 100,
@@ -30,6 +30,12 @@
 
     默认安装不包含被 Hysteria2 依赖的 QUIC，参阅 [安装](/zh/#_2)。
 
+!!! warning "与官方 Hysteria2 的区别"
+
+    官方程序支持一种名为 **userpass** 的验证方式，
+    本质上上是将用户名与密码的组合 `<username>:<password>` 作为实际上的密码，而 sing-box 不提供此别名。
+    要将 sing-box 与官方程序一起使用， 您需要填写该组合作为实际密码。
+
 ### 监听字段
 
 参阅 [监听字段](/zh/configuration/shared/listen/)。

diff --git a/docs/configuration/inbound/naive.md b/docs/configuration/inbound/naive.md
@@ -20,7 +20,7 @@
 
 !!! warning ""
 
-    HTTP3 transport is not included by default, see [Installation](/#installation).
+    HTTP3 transport is not included by default, see [Installation](./#installation).
 
 ### Listen Fields
 

diff --git a/docs/configuration/inbound/tuic.md b/docs/configuration/inbound/tuic.md
@@ -24,7 +24,7 @@
 
 !!! warning ""
 
-    QUIC, which is required by TUIC is not included by default, see [Installation](/#installation).
+    QUIC, which is required by TUIC is not included by default, see [Installation](./#installation).
 
 ### Listen Fields
 

diff --git a/docs/configuration/inbound/tun.md b/docs/configuration/inbound/tun.md
@@ -171,7 +171,7 @@ TCP/IP stack.
 
 !!! warning ""
 
-    gVisor and LWIP stacks is not included by default, see [Installation](/#installation).
+    gVisor and LWIP stacks is not included by default, see [Installation](./#installation).
 
 #### include_interface
 

diff --git a/docs/configuration/outbound/hysteria.md b/docs/configuration/outbound/hysteria.md
@@ -26,7 +26,7 @@
 
 !!! warning ""
 
-    QUIC, which is required by hysteria is not included by default, see [Installation](/#installation).
+    QUIC, which is required by hysteria is not included by default, see [Installation](./#installation).
 
 ### Fields