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/en/troubleshooting.mdx | 525 ---------------------------
 1 file changed, 525 deletions(-)
 delete mode 100644 packages/docs/content/en/troubleshooting.mdx

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

diff --git a/packages/docs/content/en/troubleshooting.mdx b/packages/docs/content/en/troubleshooting.mdx
deleted file mode 100644
index 6d97819..0000000
--- a/packages/docs/content/en/troubleshooting.mdx
+++ /dev/null
@@ -1,525 +0,0 @@
----
-title: Troubleshooting
-description: Common issues and solutions for DropOut launcher
----
-
-# Troubleshooting
-
-This guide covers common issues and their solutions. If you don't find your issue here, please [open an issue](https://github.com/HydroRoll-Team/DropOut/issues) on GitHub.
-
-## Installation Issues
-
-### Linux: Missing Dependencies
-
-**Issue:** Error about missing libraries during installation
-
-**Solution:**
-```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: "App is damaged"
-
-**Issue:** macOS says DropOut is damaged and can't be opened
-
-**Solution:**
-1. Open Terminal
-2. Run: `xattr -cr /Applications/DropOut.app`
-3. Try opening again
-4. Or: System Preferences → Security → Allow anyway
-
-### Windows: SmartScreen Warning
-
-**Issue:** Windows SmartScreen blocks the installer
-
-**Solution:**
-1. Click "More info"
-2. Click "Run anyway"
-3. This is normal for new apps without extended validation certificates
-
-## Authentication Issues
-
-### Microsoft Login Fails
-
-**Issue:** Can't complete Microsoft login
-
-**Possible causes and solutions:**
-
-**1. Device code expired:**
-- Codes expire after 15 minutes
-- Start the login process again
-- Complete authorization faster
-
-**2. Network issues:**
-- Check internet connection
-- Disable VPN temporarily
-- Check firewall settings
-- Try different network
-
-**3. Microsoft account issues:**
-- Verify account owns Minecraft Java Edition
-- Check at https://www.minecraft.net/profile
-- Ensure account is not suspended
-
-**4. Browser problems:**
-- Try different browser
-- Clear browser cache
-- Disable ad blockers
-- Use incognito/private mode
-
-### Token Refresh Fails
-
-**Issue:** Token refresh fails, must re-login frequently
-
-**Solution:**
-1. Log out completely
-2. Delete `accounts.json` from app data directory
-3. Log in again
-4. If persists, check Microsoft account status
-
-### Offline Login Not Working
-
-**Issue:** Can't create offline account
-
-**Solution:**
-- Username must be 3-16 characters
-- Use only letters, numbers, underscore
-- No special characters
-- No spaces
-
-## Game Launch Issues
-
-### Java Not Found
-
-**Issue:** "No Java installation found"
-
-**Solutions:**
-
-**1. Auto-detect existing Java:**
-- Settings → Java → Detect Installations
-- If found, select it
-- If not found, proceed to step 2
-
-**2. Download Java via DropOut:**
-- Settings → Java → Download Java
-- Select appropriate version:
-  - Java 8 for Minecraft 1.12.2 and older
-  - Java 17 for Minecraft 1.18-1.20.4
-  - Java 21 for Minecraft 1.20.5+
-
-**3. Manual Java installation:**
-- Download from [Adoptium](https://adoptium.net/)
-- Install to system
-- Restart DropOut
-- Detect again
-
-### Wrong Java Version
-
-**Issue:** Game crashes with "Unsupported class file version"
-
-**Solution:**
-Match Java version to Minecraft version:
-
-| Minecraft Version | Java Version |
-|-------------------|--------------|
-| 1.7.10 and older  | Java 8       |
-| 1.8 - 1.12.2      | Java 8       |
-| 1.13 - 1.16.5     | Java 8 or 11 |
-| 1.17 - 1.17.1     | Java 16      |
-| 1.18 - 1.20.4     | Java 17      |
-| 1.20.5+           | Java 21      |
-
-### OutOfMemoryError
-
-**Issue:** Game crashes with `java.lang.OutOfMemoryError`
-
-**Solutions:**
-
-**1. Increase memory allocation:**
-- Settings → Memory
-- Increase Maximum Memory:
-  - Vanilla: 4GB minimum
-  - Light mods: 6GB
-  - Heavy modpacks: 8-12GB
-- Don't exceed 80% of system RAM
-
-**2. Use 64-bit Java:**
-- Check current Java architecture
-- Download 64-bit Java if needed
-- 32-bit Java limited to ~2GB
-
-**3. Reduce render distance:**
-- In-game Video Settings
-- Lower render distance to 8-12 chunks
-
-**4. Optimize JVM arguments:**
-```bash
--Xms4G -Xmx8G -XX:+UseG1GC -XX:+UnlockExperimentalVMOptions
-```
-
-### Game Won't Start
-
-**Issue:** Game doesn't launch, no error message
-
-**Check:**
-
-**1. Log output:**
-- Check game console in DropOut
-- Look for error messages
-- Common issues:
-  - Missing files
-  - Corrupted downloads
-  - Mod conflicts
-
-**2. Verify files:**
-- Delete version folder
-- Re-download version
-- Try vanilla first before modded
-
-**3. Check permissions:**
-- Ensure DropOut can write to game directory
-- Check folder permissions
-- On Linux: ensure the launcher directory is only accessible by your user, e.g. `chmod 700 ~/.local/share/com.dropout.launcher`
-
-## Download Issues
-
-### Downloads Fail
-
-**Issue:** Asset or library downloads fail
-
-**Solutions:**
-
-**1. Network issues:**
-- Check internet connection
-- Disable VPN
-- Try different network
-- Check firewall/antivirus
-
-**2. Resume downloads:**
-- DropOut auto-resumes interrupted downloads
-- Close and reopen DropOut
-- Downloads should continue
-
-**3. Clear download cache:**
-- Delete `.part` files in libraries/assets
-- Restart download
-
-**4. Manually download:**
-- Check logs for failing URL
-- Download file manually
-- Place in correct location
-
-### Slow Downloads
-
-**Issue:** Downloads are very slow
-
-**Solutions:**
-
-**1. Adjust thread count:**
-- Settings → Downloads
-- Try different thread counts:
-  - Too low: slow overall
-  - Too high: connection throttling
-  - Recommended: 5-10 threads
-
-**2. Network optimization:**
-- Close bandwidth-heavy apps
-- Use wired connection if possible
-- Check for ISP throttling
-
-**3. Alternative CDN:**
-- Mojang mirrors may be slow
-- Try at different time of day
-
-## Mod Loader Issues
-
-### Fabric Installation Fails
-
-**Issue:** Can't install Fabric loader
-
-**Solutions:**
-
-**1. Check Minecraft version:**
-- Fabric supports 1.14+
-- Older versions not supported
-- Try newer Minecraft version
-
-**2. Network issues:**
-- Check internet connection
-- Fabric Meta API may be down
-- Try again later
-
-**3. Manual installation:**
-- Download Fabric from [fabricmc.net](https://fabricmc.net/)
-- Use official installer
-- Import profile to DropOut
-
-### Forge Installation Fails
-
-**Issue:** Forge installer fails or hangs
-
-**Solutions:**
-
-**1. Java version:**
-- Ensure correct Java version
-- Forge 1.17+ requires Java 16+
-- Older Forge may need Java 8
-
-**2. Installer timeout:**
-- Forge installer can be slow
-- Wait up to 10 minutes
-- Check logs for progress
-
-**3. Disk space:**
-- Ensure sufficient free space
-- Forge needs ~1GB temporarily
-- Check `/tmp` on Linux
-
-**4. Manual installation:**
-- Download Forge installer from [minecraftforge.net](https://files.minecraftforge.net/)
-- Run installer manually
-- Select install client
-- Import profile
-
-### Mod Crashes
-
-**Issue:** Game crashes with mods installed
-
-**Solutions:**
-
-**1. Check compatibility:**
-- Verify mod is for correct Minecraft version
-- Check mod loader version requirements
-- Read mod description for dependencies
-
-**2. Install dependencies:**
-- Fabric mods often need Fabric API
-- Some mods require libraries
-- Check crash log for "missing" errors
-
-**3. Remove conflicting mods:**
-- Disable mods one by one
-- Identify problematic mod
-- Check for known conflicts
-- Update or replace mod
-
-**4. Update mods:**
-- Use latest mod versions
-- Check mod update notes
-- Some updates fix crashes
-
-## Performance Issues
-
-### Low FPS
-
-**Issue:** Game runs slowly or stutters
-
-**Solutions:**
-
-**1. Allocate more memory:**
-- Increase max memory to 6-8GB
-- Don't over-allocate (causes GC pauses)
-
-**2. Install performance mods:**
-- **Fabric**: Sodium, Lithium, Phosphor
-- **Forge**: OptiFine, Magnesium, Rubidium
-
-**3. Optimize settings:**
-- Lower render distance
-- Disable fancy graphics
-- Turn off particles
-- Disable VSync if fps < 60
-
-**4. Update graphics drivers:**
-- Download latest from manufacturer
-- NVIDIA: GeForce Experience
-- AMD: Adrenalin
-- Intel: Graphics Command Center
-
-**5. Close background apps:**
-- Free up system resources
-- Disable overlays (Discord, etc.)
-- Check Task Manager for CPU/RAM hogs
-
-### Launcher Slow to Start
-
-**Issue:** DropOut takes long time to launch
-
-**Solutions:**
-
-**1. Check system resources:**
-- Close unnecessary programs
-- Ensure sufficient RAM available
-- Check CPU usage
-
-**2. Antivirus interference:**
-- Add DropOut to exceptions
-- Temporarily disable to test
-- Some AVs slow down significantly
-
-**3. Corrupted data:**
-- Delete `cache` folder in app data
-- Restart DropOut
-- Will rebuild cache
-
-## UI Issues
-
-### Window Won't Open
-
-**Issue:** DropOut window doesn't appear
-
-**Solutions:**
-
-**1. Check if running:**
-```bash
-# Linux/macOS
-ps aux | grep dropout
-
-# Windows
-tasklist | findstr dropout
-```
-
-**2. Kill and restart:**
-```bash
-# Linux/macOS
-pkill dropout
-
-# Windows
-taskkill /F /IM dropout.exe
-```
-
-**3. Reset window position:**
-- Delete window state config
-- Restart DropOut
-
-### Graphics Glitches
-
-**Issue:** UI looks wrong or has visual artifacts
-
-**Solutions:**
-
-**1. Update graphics drivers:**
-- Install latest drivers
-- Restart system
-
-**2. Disable hardware acceleration:**
-- Check if option exists in settings
-- May reduce performance but fix glitches
-
-**3. Try different monitor:**
-- Multi-monitor setups can cause issues
-- Try on different display
-
-## File System Issues
-
-### Can't Access Game Directory
-
-**Issue:** Errors accessing game files
-
-**Solutions:**
-
-**1. Check permissions:**
-```bash
-# Linux (set secure owner-only permissions)
-sudo chown -R "$USER":"$USER" ~/.local/share/com.dropout.launcher
-chmod -R u+rwX,go-rwx ~/.local/share/com.dropout.launcher
-
-# macOS (set secure owner-only permissions)
-sudo chown -R "$USER":"$USER" ~/Library/Application\ Support/com.dropout.launcher
-chmod -R u+rwX,go-rwx ~/Library/Application\ Support/com.dropout.launcher
-```
-
-**2. Check disk space:**
-- Ensure sufficient free space
-- Minecraft needs 2-10GB depending on mods
-- Clean up old versions
-
-**3. Antivirus blocking:**
-- Add game directory to exceptions
-- Some AVs block file access
-
-### Corrupted Files
-
-**Issue:** Files appear corrupted or invalid
-
-**Solutions:**
-
-**1. Verify checksums:**
-- DropOut verifies SHA1/SHA256
-- Failed verification triggers re-download
-
-**2. Re-download:**
-- Delete corrupted file
-- Launch version again
-- DropOut will re-download
-
-**3. Clear cache:**
-- Delete version folder entirely
-- Re-install from scratch
-
-## Getting More Help
-
-### Collect Debug Information
-
-When reporting issues, include:
-
-**1. System information:**
-- OS and version
-- DropOut version
-- Java version
-
-**2. Logs:**
-- Launcher logs from console
-- Game logs if applicable
-- Error messages (full text)
-
-**3. Steps to reproduce:**
-- What you did
-- What you expected
-- What actually happened
-
-**4. Screenshots:**
-- Error messages
-- UI issues
-- Settings screens
-
-### Report Issues
-
-1. Search [existing issues](https://github.com/HydroRoll-Team/DropOut/issues)
-2. If not found, [create new issue](https://github.com/HydroRoll-Team/DropOut/issues/new)
-3. Use issue template
-4. Provide all requested information
-5. Be patient and responsive
-
-### Community Support
-
-- **GitHub Discussions**: Ask questions
-- **Discord**: Real-time help (if available)
-- **Documentation**: Check all guides
-
-## Known Issues
-
-### Currently Being Worked On
-
-- Multi-account switching (in progress)
-- Custom game directory selection (planned)
-- Launcher auto-update (planned)
-
-### Workarounds Available
-
-**Issue**: Can't switch between accounts easily
-**Workaround**: Log out and log in with different account
-
-**Issue**: No built-in mod manager
-**Workaround**: Manually manage mods in instance folder
-
-**Issue**: Can't import from other launchers
-**Workaround**: Manually copy instance files
-- 
cgit v1.2.3-70-g09d2

