Restructure docs into manual/development and add implementation docs (#94)

## 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>

1 files changed, 525 insertions, 0 deletions

diff --git a/packages/docs/content/en/manual/troubleshooting.mdx b/packages/docs/content/en/manual/troubleshooting.mdx
new file mode 100644
index 0000000..6d97819
--- /dev/null
+++ b/packages/docs/content/en/manual/troubleshooting.mdx
@@ -0,0 +1,525 @@
+---
+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