Initialize OpenXlings website

Author: Sunrisepeak

.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*

README.md

@@ -0,0 +1,25 @@
+# OpenXlings Website
+
+OpenXlings organization website and xlings documentation, built with Docusaurus.
+
+## Development
+
+```bash
+npm install
+npm run start
+```
+
+## Validate
+
+```bash
+npm run typecheck
+npm run build
+```
+
+## Content Sources
+
+- xlings usage and install commands: `openxlings/xlings`
+- Package index: `openxlings/xim-pkgindex`
+- xpkg and libxpkg references: `openxlings/xim-pkgindex` and `openxlings/libxpkg`
+
+Keep command examples aligned with current xlings code before publishing.

docs/faq.md

@@ -0,0 +1,126 @@
+---
+sidebar_position: 100
+title: 常见问题
+---
+
+# 常见问题
+
+## 安装相关
+
+### 安装命令执行后没有反应？
+
+请确保网络可以正常访问 GitHub。如果访问受限，可以通过 `XLINGS_GITHUB_MIRROR` 指定镜像：
+
+```bash
+XLINGS_GITHUB_MIRROR=https://mirror.example.com \
+  curl -fsSL https://mirror.example.com/openxlings/xlings/main/tools/other/quick_install.sh | bash
+```
+
+Windows PowerShell：
+
+```powershell
+$env:XLINGS_GITHUB_MIRROR = "https://mirror.example.com"
+powershell -ExecutionPolicy Bypass -c "irm https://mirror.example.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex"
+```
+
+### 安装后命令找不到？
+
+安装完成后需要重新打开终端，或手动加载 shell 配置：
+
+```bash
+source ~/.bashrc    # bash
+source ~/.zshrc     # zsh
+```
+
+### 如何更新 xlings 本身？
+
+```bash
+# 重新运行安装命令即可更新到最新版本
+curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/refs/heads/main/tools/other/quick_install.sh | bash
+```
+
+## 包管理
+
+### 搜索不到想要的包？
+
+先更新包索引：
+
+```bash
+xlings update
+```
+
+如果仍然找不到，说明该软件尚未收录到 xim-pkgindex。欢迎通过 [Pull Request](https://github.com/openxlings/xim-pkgindex) 添加新包。
+
+### 安装包时下载太慢？
+
+可以配置镜像源。在 `.xlings.json` 中设置：
+
+```json
+{
+  "mirror": "CN"
+}
+```
+
+### 如何同时安装多个版本？
+
+直接安装不同版本即可，xlings 支持多版本共存：
+
+```bash
+xlings install gcc@15
+xlings install gcc@13
+```
+
+然后用 `xlings use` 切换：
+
+```bash
+xlings use gcc 15
+xlings use gcc 13
+```
+
+## SubOS
+
+### subos 之间的包会重复下载吗？
+
+不会。所有 subos 共享同一份包 payload，通过引用计数管理生命周期。只有最后一个引用被移除时才会清理 payload。
+
+### 删除 subos 后磁盘空间没有释放？
+
+删除 subos 只移除该 subos 的版本视图和配置。如果其他 subos 仍在使用相同的包，payload 不会被删除。可以用以下命令清理无引用的 payload：
+
+```bash
+xlings self clean
+```
+
+### shell-level 和 global 模式有什么区别？
+
+- **shell-level**（默认）：启动一个子 shell，退出后回到原环境
+- **global**（`--global`）：修改全局指针，影响所有新打开的终端
+
+推荐日常使用 shell-level 模式，避免意外影响全局环境。
+
+## Sandbox
+
+### Sandbox 和普通 subos 有什么区别？
+
+普通 subos 只隔离 PATH 和环境变量，共享宿主的 `$HOME` 和 dotfile。Sandbox 通过 proot/bwrap 实现文件系统级隔离，拥有独立的 `$HOME`、dotfile 和 `/etc`。
+
+### 为什么 Sandbox 只支持 Linux？
+
+Sandbox 依赖 Linux 特有的 proot 或 bubblewrap (bwrap) 工具来实现文件系统视图重定向。macOS 和 Windows 没有等效机制。
+
+## 其他
+
+### xlings 和 Homebrew / apt / pacman 有什么不同？
+
+xlings 的核心区别在于：
+
+1. **多版本管理**：原生支持同一工具的多版本共存和切换
+2. **跨平台**：同一套命令在 Linux、macOS、Windows 上通用
+3. **环境隔离**：SubOS 机制提供工作空间级别的隔离
+4. **万物皆可包**：不仅安装软件，还能安装配置、教程等
+
+### 如何参与贡献？
+
+- [添加新包](https://github.com/openxlings/xim-pkgindex)
+- [报告问题](https://github.com/openxlings/xlings/issues)
+- [社区论坛](https://forum.d2learn.org/category/9/xlings)

docs/guide/package-management.md

@@ -0,0 +1,112 @@
+---
+sidebar_position: 1
+title: 包管理
+---
+
+# 包管理
+
+xlings 内置包管理器 xim（Xlings Installation Manager），支持软件安装、环境配置、教程安装等多种包类型。
+
+## 安装软件
+
+```bash
+# 安装最新版本
+xlings install gcc
+xlings install node
+
+# 安装指定版本
+xlings install gcc@15
+xlings install node@24
+
+# 一次安装多个包
+xlings install gcc@15 node@24 pnpm
+
+# 跳过确认提示
+xlings install gcc@15 -y
+```
+
+## 安装环境配置
+
+xlings 不仅能安装软件，还能一键配置开发环境：
+
+```bash
+# 配置 Rust crates 镜像
+xlings install config:rust-crates-mirror
+```
+
+## 安装教程
+
+```bash
+# 安装交互式 C++ 教程
+xlings install d2x:mcpp-standard
+```
+
+## 卸载软件
+
+```bash
+xlings remove gcc
+xlings remove node
+```
+
+## 搜索软件
+
+```bash
+xlings search gcc
+xlings search node
+```
+
+搜索结果会显示包名、描述、可用版本等信息。
+
+## 列出已安装的包
+
+```bash
+# 列出所有已安装的包
+xlings list
+
+# 过滤显示
+xlings list gcc
+```
+
+## 查看包信息
+
+```bash
+xlings info gcc
+```
+
+显示包的详细信息，包括描述、可用版本、依赖关系、支持平台等。
+
+## 更新包索引
+
+```bash
+xlings update
+```
+
+从远程同步最新的包索引数据。建议在搜索或安装之前先更新索引。
+
+## 项目级依赖管理
+
+在项目根目录创建 `.xlings.json` 文件，声明项目所需的工具和版本：
+
+```json
+{
+  "workspace": {
+    "xmake": "3.0.7",
+    "cmake": "4.0.2",
+    "ninja": "1.12.1",
+    "gcc": { "linux": "15.1.0" },
+    "llvm": { "macos": "20" }
+  }
+}
+```
+
+然后一条命令安装所有依赖：
+
+```bash
+xlings install
+```
+
+`workspace` 中的值可以是版本字符串，也可以是按平台区分的对象（`linux`、`macos`、`windows`），实现跨平台项目配置。
+
+## 包索引
+
+xlings 的包来自 [xim-pkgindex](https://github.com/openxlings/xim-pkgindex) 索引仓库。你也可以添加自定义索引仓库来扩展可用包集合。

docs/guide/sandbox.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 4
+title: Sandbox 沙箱
+---
+
+# Sandbox 沙箱模式
+
+Sandbox 是 SubOS 的文件系统隔离进入方式。与普通 subos 的 PATH/env 隔离不同，sandbox 通过 bwrap 或 proot 提供隔离的 `$HOME`、dotfile、`/tmp` 和最小 `/etc` 视图。
+
+:::info 平台限制
+Sandbox 模式仅支持 Linux。macOS 和 Windows 上不可用。
+:::
+
+## 创建并进入 Sandbox
+
+Sandbox 不是创建时的独立类型，而是进入 subos 时的模式：
+
+```bash
+xlings subos new mybox
+xlings subos use mybox --sandbox
+```
+
+xlings 会复用当前 shell，并为该 subos 懒初始化 sandbox 私有目录和最小系统文件。
+
+如果需要指定后端，可以显式传入：
+
+```bash
+xlings subos use mybox --sandbox bwrap
+xlings subos use mybox --sandbox proot
+```
+
+进入后你会发现：
+- `$HOME` 指向 sandbox 私有的 `/home/<user>` 目录
+- 所有 dotfile（`.gitconfig`、`.npm/`、`.cache/` 等）完全独立
+- 优先使用 bwrap，受限环境下回退到 proot
+- xlings 是 sandbox 内唯一的包管理器
+
+## 在 Sandbox 中安装工具
+
+```bash
+# 进入 sandbox
+xlings subos use mybox --sandbox
+
+# 安装 gcc
+xlings install gcc@15 -y
+gcc --version
+
+# 安装 node
+xlings install node@24 -y
+node --version
+```
+
+安装的工具仅在此 sandbox 内可见，不影响宿主环境或其他 subos。
+
+## 三种 SubOS 模式对比
+
+| | global | shell-level | sandbox |
+|---|---|---|---|
+| **创建** | `subos new foo` | `subos new foo` | `subos new foo` |
+| **进入** | `subos use foo --global` | `subos use foo` | `subos use foo --sandbox` |
+| **隔离级别** | PATH 优先级 | 子 shell + env | 文件系统视图 |
+| **$HOME** | 宿主主目录 | 宿主主目录 | sandbox 私有 |
+| **dotfile** | 共享宿主 | 共享宿主 | 完全独立 |
+| **后端** | env | env spawn shell | bwrap / proot |
+| **平台** | 全平台 | 全平台 | 仅 Linux |
+
+## 使用场景
+
+- **隔离构建环境**：编译项目时不污染宿主 dotfile 和缓存
+- **跨发行版测试**：在不同 sandbox 中测试不同的工具链组合
+- **清理实验**：尝试新工具后直接删除 sandbox，宿主一尘不染
+- **AI Agent 操场**：给 LLM agent 一个干净的沙箱环境
+
+## 后端
+
+xlings sandbox 支持双后端，自动检测可用后端：
+
+| 后端 | 说明 |
+|------|------|
+| **proot** | 无需特权，用户态文件系统重定向，零 sudo |
+| **bwrap** (bubblewrap) | 基于 Linux namespace，更强的隔离性 |
+
+xlings 会优先使用 bwrap（如果可用），否则自动回退到 proot。
+
+## 删除 Sandbox
+
+```bash
+xlings subos remove mybox
+```
+
+删除 sandbox 会清除其私有的根目录，包括所有 dotfile。共享的包 payload 不受影响。