From 81a62402ef6f8900ff092366121a9b7a4263ba52 Mon Sep 17 00:00:00 2001
From: Natsuu <natsukawa247@outlook.com>
Date: Fri, 27 Feb 2026 17:18:25 +0800
Subject: Restructure docs into manual/development and add implementation docs
 (#94)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary by Sourcery

Restructure documentation into separate manual and development sections,
introduce detailed internal implementation docs for auth/Java/mod
loaders, and update site navigation, landing page links, and MDX tooling
(Mermaid, card styling) to match the new structure and tech stack.

Enhancements:
- Enable Mermaid rendering support in the docs app and add a reusable
Mermaid React component.
- Refine Docs page rendering by customizing Card styling and removing
redundant in-page titles/descriptions rendered by the layout.
- Align docs source configuration and routing comments with the new
manual-based default paths.

Documentation:
- Split user-facing docs under a new manual section and move contributor
content into a dedicated development section for both English and
Chinese.
- Add comprehensive internal implementation documentation covering
authentication, Java management, mod loader/version merging, event bus,
and architecture patterns in both English and Chinese.
- Update existing feature docs (mod loaders, Java, authentication) and
getting-started/troubleshooting pages to be more conceptual, pointing to
implementation docs for technical details.
- Refresh architecture docs to reflect the React/Zustand frontend stack
and add Mermaid-based architecture diagrams.
- Adjust navigation labels, home-page CTAs, and doc links to target the
new manual/development structure and routes.

---------

Co-authored-by: 简律纯 <i@jyunko.cn>
---
 packages/docs/content/zh/troubleshooting.mdx | 523 ---------------------------
 1 file changed, 523 deletions(-)
 delete mode 100644 packages/docs/content/zh/troubleshooting.mdx

(limited to 'packages/docs/content/zh/troubleshooting.mdx')

diff --git a/packages/docs/content/zh/troubleshooting.mdx b/packages/docs/content/zh/troubleshooting.mdx
deleted file mode 100644
index c077528..0000000
--- a/packages/docs/content/zh/troubleshooting.mdx
+++ /dev/null
@@ -1,523 +0,0 @@
----
-title: 故障排除
-description: DropOut 启动器常见问题和解决方案
----
-
-# 故障排除
-
-本指南涵盖常见问题及其解决方案。如果在这里找不到你的问题，请在 GitHub 上[提交 issue](https://github.com/HydroRoll-Team/DropOut/issues)。
-
-## 安装问题
-
-### Linux：缺少依赖
-
-**问题：** 安装时提示缺少库
-
-**解决方案：**
-```bash
-# Ubuntu/Debian
-sudo apt update
-sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0
-
-# Fedora
-sudo dnf install webkit2gtk4.1 gtk3
-
-# Arch
-sudo pacman -S webkit2gtk gtk3
-```
-
-### macOS："应用程序已损坏"
-
-**问题：** macOS 提示 DropOut 已损坏无法打开
-
-**解决方案：**
-1. 打开终端
-2. 运行：`xattr -cr /Applications/DropOut.app`
-3. 再次尝试打开
-4. 或者：系统偏好设置 → 安全性 → 仍要打开
-
-### Windows：SmartScreen 警告
-
-**问题：** Windows SmartScreen 阻止安装程序
-
-**解决方案：**
-1. 点击"更多信息"
-2. 点击"仍要运行"
-3. 这对于没有扩展验证证书的新应用是正常的
-
-## 身份验证问题
-
-### Microsoft 登录失败
-
-**问题：** 无法完成 Microsoft 登录
-
-**可能原因和解决方案：**
-
-**1. 设备代码过期：**
-- 代码在 15 分钟后过期
-- 重新开始登录过程
-- 更快地完成授权
-
-**2. 网络问题：**
-- 检查互联网连接
-- 暂时禁用 VPN
-- 检查防火墙设置
-- 尝试不同的网络
-
-**3. Microsoft 账户问题：**
-- 验证账户拥有 Minecraft Java 版
-- 在 https://www.minecraft.net/profile 检查
-- 确保账户未被封禁
-
-**4. 浏览器问题：**
-- 尝试不同的浏览器
-- 清除浏览器缓存
-- 禁用广告拦截器
-- 使用无痕/隐私模式
-
-### 令牌刷新失败
-
-**问题：** 令牌刷新失败，必须频繁重新登录
-
-**解决方案：**
-1. 完全退出登录
-2. 从应用数据目录删除 `accounts.json`
-3. 重新登录
-4. 如果持续存在，检查 Microsoft 账户状态
-
-### 离线登录不工作
-
-**问题：** 无法创建离线账户
-
-**解决方案：**
-- 用户名必须是 3-16 个字符
-- 仅使用字母、数字、下划线
-- 不使用特殊字符
-- 不使用空格
-
-## 游戏启动问题
-
-### 找不到 Java
-
-**问题：** "未找到 Java 安装"
-
-**解决方案：**
-
-**1. 自动检测现有 Java：**
-- 设置 → Java → 检测安装
-- 如果找到，选择它
-- 如果未找到，进行步骤 2
-
-**2. 通过 DropOut 下载 Java：**
-- 设置 → Java → 下载 Java
-- 选择适当的版本：
-  - Java 8 用于 Minecraft 1.12.2 及更早版本
-  - Java 17 用于 Minecraft 1.18-1.20.4
-  - Java 21 用于 Minecraft 1.20.5+
-
-**3. 手动安装 Java：**
-- 从 [Adoptium](https://adoptium.net/) 下载
-- 安装到系统
-- 重启 DropOut
-- 再次检测
-
-### Java 版本错误
-
-**问题：** 游戏崩溃并提示"不支持的类文件版本"
-
-**解决方案：**
-将 Java 版本与 Minecraft 版本匹配：
-
-| Minecraft 版本 | Java 版本 |
-|-------------------|--------------|
-| 1.7.10 及更早  | Java 8       |
-| 1.8 - 1.12.2      | Java 8       |
-| 1.13 - 1.16.5     | Java 8 或 11 |
-| 1.17 - 1.17.1     | Java 16      |
-| 1.18 - 1.20.4     | Java 17      |
-| 1.20.5+           | Java 21      |
-
-### 内存不足错误
-
-**问题：** 游戏崩溃并显示 `java.lang.OutOfMemoryError`
-
-**解决方案：**
-
-**1. 增加内存分配：**
-- 设置 → 内存
-- 增加最大内存：
-  - 原版：最少 4GB
-  - 轻度模组：6GB
-  - 重度整合包：8-12GB
-- 不要超过系统 RAM 的 80%
-
-**2. 使用 64 位 Java：**
-- 检查当前 Java 架构
-- 如需要下载 64 位 Java
-- 32 位 Java 限制在约 2GB
-
-**3. 降低渲染距离：**
-- 游戏内视频设置
-- 将渲染距离降低到 8-12 区块
-
-**4. 优化 JVM 参数：**
-```bash
--Xms4G -Xmx8G -XX:+UseG1GC -XX:+UnlockExperimentalVMOptions
-```
-
-### 游戏无法启动
-
-**问题：** 游戏不启动，没有错误消息
-
-**检查：**
-
-**1. 日志输出：**
-- 检查 DropOut 中的游戏控制台
-- 查找错误消息
-- 常见问题：
-  - 文件缺失
-  - 下载损坏
-  - 模组冲突
-
-**2. 验证文件：**
-- 删除版本文件夹
-- 重新下载版本
-- 在模组版本之前先尝试原版
-
-**3. 检查权限：**
-- 确保 DropOut 可以写入游戏目录
-- 检查文件夹权限
-- 在 Linux 上：`chmod -R 700 ~/.local/share/com.dropout.launcher`（仅当前用户可访问）
-
-## 下载问题
-
-### 下载失败
-
-**问题：** 资源或库下载失败
-
-**解决方案：**
-
-**1. 网络问题：**
-- 检查互联网连接
-- 禁用 VPN
-- 尝试不同的网络
-- 检查防火墙/杀毒软件
-
-**2. 恢复下载：**
-- DropOut 自动恢复中断的下载
-- 关闭并重新打开 DropOut
-- 下载应该继续
-
-**3. 清除下载缓存：**
-- 删除 libraries/assets 中的 `.part` 文件
-- 重新开始下载
-
-**4. 手动下载：**
-- 检查日志中失败的 URL
-- 手动下载文件
-- 放置在正确位置
-
-### 下载缓慢
-
-**问题：** 下载非常慢
-
-**解决方案：**
-
-**1. 调整线程数：**
-- 设置 → 下载
-- 尝试不同的线程数：
-  - 太低：整体较慢
-  - 太高：连接限流
-  - 推荐：5-10 个线程
-
-**2. 网络优化：**
-- 关闭占用大量带宽的应用
-- 如可能使用有线连接
-- 检查 ISP 限速
-
-**3. 备用 CDN：**
-- Mojang 镜像可能很慢
-- 尝试在一天中的不同时间
-
-## 模组加载器问题
-
-### Fabric 安装失败
-
-**问题：** 无法安装 Fabric 加载器
-
-**解决方案：**
-
-**1. 检查 Minecraft 版本：**
-- Fabric 支持 1.14+
-- 不支持更早版本
-- 尝试更新的 Minecraft 版本
-
-**2. 网络问题：**
-- 检查互联网连接
-- Fabric Meta API 可能宕机
-- 稍后再试
-
-**3. 手动安装：**
-- 从 [fabricmc.net](https://fabricmc.net/) 下载 Fabric
-- 使用官方安装器
-- 将配置文件导入 DropOut
-
-### Forge 安装失败
-
-**问题：** Forge 安装器失败或挂起
-
-**解决方案：**
-
-**1. Java 版本：**
-- 确保 Java 版本正确
-- Forge 1.17+ 需要 Java 16+
-- 更早的 Forge 可能需要 Java 8
-
-**2. 安装器超时：**
-- Forge 安装器可能很慢
-- 等待最多 10 分钟
-- 检查日志查看进度
-
-**3. 磁盘空间：**
-- 确保有足够的可用空间
-- Forge 临时需要约 1GB
-- 检查 Linux 上的 `/tmp`
-
-**4. 手动安装：**
-- 从 [minecraftforge.net](https://files.minecraftforge.net/) 下载 Forge 安装器
-- 手动运行安装器
-- 选择安装客户端
-- 导入配置文件
-
-### 模组崩溃
-
-**问题：** 安装模组后游戏崩溃
-
-**解决方案：**
-
-**1. 检查兼容性：**
-- 验证模组适用于正确的 Minecraft 版本
-- 检查模组加载器版本要求
-- 阅读模组说明了解依赖项
-
-**2. 安装依赖项：**
-- Fabric 模组通常需要 Fabric API
-- 一些模组需要库
-- 检查崩溃日志中的"缺失"错误
-
-**3. 移除冲突的模组：**
-- 逐一禁用模组
-- 识别有问题的模组
-- 检查已知冲突
-- 更新或替换模组
-
-**4. 更新模组：**
-- 使用最新的模组版本
-- 检查模组更新说明
-- 一些更新修复崩溃
-
-## 性能问题
-
-### 低 FPS
-
-**问题：** 游戏运行缓慢或卡顿
-
-**解决方案：**
-
-**1. 分配更多内存：**
-- 将最大内存增加到 6-8GB
-- 不要过度分配（导致 GC 暂停）
-
-**2. 安装性能模组：**
-- **Fabric**: Sodium、Lithium、Phosphor
-- **Forge**: OptiFine、Magnesium、Rubidium
-
-**3. 优化设置：**
-- 降低渲染距离
-- 禁用精美图形
-- 关闭粒子
-- 如果 fps < 60 禁用垂直同步
-
-**4. 更新显卡驱动：**
-- 从制造商下载最新版本
-- NVIDIA: GeForce Experience
-- AMD: Adrenalin
-- Intel: Graphics Command Center
-
-**5. 关闭后台应用：**
-- 释放系统资源
-- 禁用覆盖层（Discord 等）
-- 检查任务管理器中的 CPU/RAM 占用
-
-### 启动器启动缓慢
-
-**问题：** DropOut 启动时间很长
-
-**解决方案：**
-
-**1. 检查系统资源：**
-- 关闭不必要的程序
-- 确保有足够的 RAM 可用
-- 检查 CPU 使用率
-
-**2. 杀毒软件干扰：**
-- 将 DropOut 添加到例外
-- 暂时禁用以测试
-- 一些杀毒软件会显著减慢速度
-
-**3. 损坏的数据：**
-- 删除应用数据中的 `cache` 文件夹
-- 重启 DropOut
-- 将重建缓存
-
-## UI 问题
-
-### 窗口不打开
-
-**问题：** DropOut 窗口不出现
-
-**解决方案：**
-
-**1. 检查是否在运行：**
-```bash
-# Linux/macOS
-ps aux | grep dropout
-
-# Windows
-tasklist | findstr dropout
-```
-
-**2. 终止并重启：**
-```bash
-# Linux/macOS
-pkill dropout
-
-# Windows
-taskkill /F /IM dropout.exe
-```
-
-**3. 重置窗口位置：**
-- 删除窗口状态配置
-- 重启 DropOut
-
-### 图形故障
-
-**问题：** UI 看起来不对或有视觉伪影
-
-**解决方案：**
-
-**1. 更新显卡驱动：**
-- 安装最新驱动
-- 重启系统
-
-**2. 禁用硬件加速：**
-- 检查设置中是否存在选项
-- 可能会降低性能但修复故障
-
-**3. 尝试不同的显示器：**
-- 多显示器设置可能导致问题
-- 在不同显示器上尝试
-
-## 文件系统问题
-
-### 无法访问游戏目录
-
-**问题：** 访问游戏文件时出错
-
-**解决方案：**
-
-**1. 检查权限：**
-```bash
-# Linux
-chmod -R 700 ~/.local/share/com.dropout.launcher
-
-# macOS
-chmod -R 700 ~/Library/Application\ Support/com.dropout.launcher
-```
-
-**2. 检查磁盘空间：**
-- 确保有足够的可用空间
-- Minecraft 需要 2-10GB，取决于模组
-- 清理旧版本
-
-**3. 杀毒软件阻止：**
-- 将游戏目录添加到例外
-- 一些杀毒软件会阻止文件访问
-
-### 文件损坏
-
-**问题：** 文件似乎损坏或无效
-
-**解决方案：**
-
-**1. 验证校验和：**
-- DropOut 验证 SHA1/SHA256
-- 验证失败会触发重新下载
-
-**2. 重新下载：**
-- 删除损坏的文件
-- 再次启动版本
-- DropOut 将重新下载
-
-**3. 清除缓存：**
-- 完全删除版本文件夹
-- 从头重新安装
-
-## 获取更多帮助
-
-### 收集调试信息
-
-报告问题时，包括：
-
-**1. 系统信息：**
-- 操作系统和版本
-- DropOut 版本
-- Java 版本
-
-**2. 日志：**
-- 控制台的启动器日志
-- 如适用的游戏日志
-- 错误消息（完整文本）
-
-**3. 重现步骤：**
-- 你做了什么
-- 你期望什么
-- 实际发生了什么
-
-**4. 截图：**
-- 错误消息
-- UI 问题
-- 设置屏幕
-
-### 报告问题
-
-1. 搜索[现有 issues](https://github.com/HydroRoll-Team/DropOut/issues)
-2. 如果未找到，[创建新 issue](https://github.com/HydroRoll-Team/DropOut/issues/new)
-3. 使用 issue 模板
-4. 提供所有要求的信息
-5. 保持耐心和响应
-
-### 社区支持
-
-- **GitHub 讨论**：提问
-- **Discord**：实时帮助（如果可用）
-- **文档**：查看所有指南
-
-## 已知问题
-
-### 目前正在处理
-
-- 多账户切换（进行中）
-- 自定义游戏目录选择（计划中）
-- 启动器自动更新（计划中）
-
-### 可用的变通方法
-
-**问题**：无法轻松切换账户
-**变通方法**：退出登录并使用不同账户登录
-
-**问题**：没有内置模组管理器
-**变通方法**：在实例文件夹中手动管理模组
-
-**问题**：无法从其他启动器导入
-**变通方法**：手动复制实例文件
-- 
cgit v1.2.3-70-g09d2

