Restructure docs into manual/development and add implementation docs#94
Merged
HsiangNianian merged 19 commits intoHydroRoll-Team:mainfrom Feb 27, 2026
Merged
Restructure docs into manual/development and add implementation docs#94HsiangNianian merged 19 commits intoHydroRoll-Team:mainfrom
HsiangNianian merged 19 commits intoHydroRoll-Team:mainfrom
Conversation
|
@NtskwK is attempting to deploy a commit to the retrofor Team on Vercel. A member of the Team first needs to authorize it. |
Contributor
Reviewer's GuideRestructures the documentation into separate user manual and development sections, simplifies user-facing feature docs by moving technical details into new internal implementation pages (EN/zh), and updates the docs app (layout, nav, MDX components, theming, diagrams, and dependencies) to support the new structure. Class diagram for docs app MDX and Mermaid integrationclassDiagram
class DocsPageClient {
+render(toc, frontmatter, Mdx): void
}
class MermaidComponent {
+chart: string
+render(): void
}
class CardComponent {
+title: string
+description: string
+href: string
+className: string
+render(): void
}
class MdxRenderer {
+components: Map
+render(mdxContent): void
}
DocsPageClient --> MdxRenderer : uses
MdxRenderer --> MermaidComponent : registers_as_Mermaid
MdxRenderer --> CardComponent : overrides_Card
Flow diagram for updated docs routing and entry pointsflowchart TB
Home["Home_page"]
DocsLinkManual["Nav_link_Manual_/docs/manual"]
DocsLinkDev["Nav_link_Development_/docs/development"]
DocsRoot["Route_/docs"]
DocsLangRoot["Route_/:lang/docs"]
ManualGettingStarted["Manual_getting_started_/docs/manual/getting-started"]
DevIndex["Development_index_/docs/development"]
Home --> DocsLinkManual
Home --> DocsLinkDev
DocsLinkManual --> ManualGettingStarted
DocsLinkDev --> DevIndex
DocsRoot -->|no_lang_or_default_lang| ManualGettingStarted
DocsLangRoot -->|non_default_lang| ManualGettingStarted
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Member
|
@SourceryAI title |
sourcery-ai
bot
changed the title
HsiangNianian
changed the title
Member
Author
|
cc @BegoniaHe |
…d enhance system architecture diagram
HsiangNianian
added
documentation
HsiangNianian
requested changes
Feb 27, 2026
.claude/settings.local.json
Outdated
HsiangNianian
changed the title
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- The new implementation docs and architecture docs disagree about the frontend stack (React + Zustand vs Svelte 5 runes and Svelte stores), and README.CN still mentions Svelte 5 as current—please align these sections so they consistently describe the actual frontend architecture and state management.
- Several new internal links point to anchors that don’t exist or don’t match the generated IDs (e.g.
../development/implementation.mdx#version-merging-mechanism,#核心库解析,#参数优化与-jvm-配置), so it would be good to adjust the headings or the fragment URLs to ensure these links resolve correctly. - The home page and header now link to
/en/docs/development, but there is nocontent/en/development/index.mdx, which will likely cause a 404 or missing landing page for the English development docs—consider adding an index file or updating the link.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new implementation docs and architecture docs disagree about the frontend stack (React + Zustand vs Svelte 5 runes and Svelte stores), and README.CN still mentions Svelte 5 as current—please align these sections so they consistently describe the actual frontend architecture and state management.
- Several new internal links point to anchors that don’t exist or don’t match the generated IDs (e.g. `../development/implementation.mdx#version-merging-mechanism`, `#核心库解析`, `#参数优化与-jvm-配置`), so it would be good to adjust the headings or the fragment URLs to ensure these links resolve correctly.
- The home page and header now link to `/en/docs/development`, but there is no `content/en/development/index.mdx`, which will likely cause a 404 or missing landing page for the English development docs—consider adding an index file or updating the link.
## Individual Comments
### Comment 1
<location path="packages/docs/content/zh/manual/features/authentication.mdx" line_range="124" />
<code_context>
+
+## API 参考
+
+关于身份验证的底层实现、OAuth 2.0 流程细节以及相关的 Tauri 命令接口，请参考开发文档：[实现细节：身份验证](../development/implementation.mdx#身份验证)。
+
+## 最佳实践
</code_context>
<issue_to_address>
**issue (bug_risk):** The `#身份验证` fragment likely doesn’t correspond to any heading ID in `implementation.mdx`.
In `zh/development/implementation.mdx`, the main auth heading is `## 1. 身份验证系统 (Authentication)`, which will slug to something like `#1-身份验证系统-authentication`, not `#身份验证`. This likely breaks the link. Please either simplify the heading so it slugs to `#身份验证`, or update this fragment to the actual MDX-generated ID.
</issue_to_address>
### Comment 2
<location path="packages/docs/app/docs/page.tsx" line_range="48-53" />
<code_context>
+ <Mdx
+ components={{
+ ...defaultMdxComponents,
+ Card: (props: any) => (
+ <Card
+ {...props}
+ className={`border-blue-600/20 hover:border-blue-600/50 transition-colors ${props.className || ''}`}
+ />
+ ),
+ Cards,
+ Mermaid
</code_context>
<issue_to_address>
**suggestion:** Using `any` for the Card MDX component props loses type safety and can hide mistakes in MDX usage.
Because this is part of MDX rendering, incorrect or missing props won’t be caught by TypeScript and will only fail at runtime. Please type `props` using the `Card` component’s props (e.g. `React.ComponentProps<typeof Card>`) instead of `any` to keep MDX usage consistent with the Card API.
Suggested implementation:
```typescript
Card: (props: React.ComponentProps<typeof Card>) => (
```
To compile successfully, this file must have access to the `React` type. If it is not already imported elsewhere in the file, add a type-only import at the top:
```ts
import type React from 'react';
```
This keeps the runtime bundle unchanged while allowing `React.ComponentProps<typeof Card>` to be used as a type.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
packages/docs/app/docs/page.tsx
Outdated
Comment on lines
48
to
53
| Card: (props: any) => ( | ||
| <Card | ||
| {...props} | ||
| className={`border-blue-600/20 hover:border-blue-600/50 transition-colors ${props.className || ''}`} | ||
| /> | ||
| ), |
Contributor
There was a problem hiding this comment.
suggestion: Using any for the Card MDX component props loses type safety and can hide mistakes in MDX usage.
Because this is part of MDX rendering, incorrect or missing props won’t be caught by TypeScript and will only fail at runtime. Please type props using the Card component’s props (e.g. React.ComponentProps<typeof Card>) instead of any to keep MDX usage consistent with the Card API.
Suggested implementation:
Card: (props: React.ComponentProps<typeof Card>) => (To compile successfully, this file must have access to the React type. If it is not already imported elsewhere in the file, add a type-only import at the top:
import type React from 'react';This keeps the runtime bundle unchanged while allowing React.ComponentProps<typeof Card> to be used as a type.
Contributor
There was a problem hiding this comment.
Pull request overview
Restructures the documentation site into distinct Manual vs Development sections, adds deep internal implementation docs (EN/ZH), and updates the docs site UI/MDX pipeline to support Mermaid diagrams and refreshed card styling.
Changes:
- Add Mermaid support to MDX rendering (remark plugin + client Mermaid component).
- Reorganize ZH docs into
/manualand/development, with new/updated meta trees and new implementation pages. - Update docs routing/navigation and home-page links/styling to reflect the new structure.
Reviewed changes
Copilot reviewed 27 out of 32 changed files in this pull request and generated 17 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/docs/source.config.ts | Enables Mermaid processing via MDX remark plugin. |
| packages/docs/package.json | Adds Mermaid + Biome; adjusts deps ordering. |
| packages/docs/content/zh/meta.json | Updates ZH root docs navigation to manual/development split. |
| packages/docs/content/zh/manual/troubleshooting.mdx | Updates wording/formatting and future-plan section labels. |
| packages/docs/content/zh/manual/meta.json | Adds manual section navigation. |
| packages/docs/content/zh/manual/index.mdx | Updates manual landing page copy. |
| packages/docs/content/zh/manual/getting-started.mdx | Updates links and formatting for the manual entrypoint. |
| packages/docs/content/zh/manual/features/mod-loaders.mdx | Refactors mod-loader docs to be conceptual and link to implementation details. |
| packages/docs/content/zh/manual/features/meta.json | Adds manual “features” section navigation. |
| packages/docs/content/zh/manual/features/java.mdx | Simplifies Java docs and references implementation details. |
| packages/docs/content/zh/manual/features/index.mdx | Adds a ZH “features overview” page. |
| packages/docs/content/zh/manual/features/authentication.mdx | Adds new ZH authentication feature doc page. |
| packages/docs/content/zh/features/authentication.mdx | Removes the old ZH authentication page (migrated to manual). |
| packages/docs/content/zh/development/meta.json | Adds ZH development section navigation. |
| packages/docs/content/zh/development/index.mdx | Updates ZH dev guide formatting and examples. |
| packages/docs/content/zh/development/implementation.mdx | Adds ZH internal implementation documentation. |
| packages/docs/content/zh/development/architecture.mdx | Updates ZH architecture doc and adds Mermaid diagrams. |
| packages/docs/content/en/getting-started.mdx | Updates EN getting-started links/formatting. |
| packages/docs/content/en/features/mod-loaders.mdx | Simplifies EN mod-loader docs and links to implementation docs. |
| packages/docs/content/en/development/meta.json | Adds EN development section navigation. |
| packages/docs/content/en/development/implementation.mdx | Adds EN internal implementation documentation. |
| packages/docs/content/en/development/guide.mdx | Adds EN development guide. |
| packages/docs/content/en/development/architecture.mdx | Updates EN architecture doc and adds Mermaid diagrams. |
| packages/docs/app/routes/home.tsx | Updates homepage CTA destinations and feature-tile styling. |
| packages/docs/app/routes/docs.tsx | Changes /docs redirect target to the new manual entry route. |
| packages/docs/app/lib/source.ts | Updates comments/examples for the new manual entry routes. |
| packages/docs/app/lib/layout.shared.tsx | Splits top nav into Manual + Development. |
| packages/docs/app/docs/page.tsx | Customizes MDX Card styling; adds Mermaid MDX component mapping; hides title/description. |
| packages/docs/app/components/mermaid.tsx | Adds client-side Mermaid renderer component. |
| README.CN.md | Updates Chinese README intro sentence. |
| .claude/settings.local.json | Adds local Claude settings file. |
Comments suppressed due to low confidence (8)
packages/docs/content/zh/manual/getting-started.mdx:128
- In the zh docs, troubleshooting was moved under the manual section (
content/zh/manual/troubleshooting.mdx). This Card still links to/docs/troubleshooting, which will 404 for the default locale; please update it to/docs/manual/troubleshooting(or a relative link).
packages/docs/content/zh/manual/getting-started.mdx:151 - This link points to
/docs/troubleshooting, but there is no longer acontent/zh/troubleshooting.mdxpage. Update to/docs/manual/troubleshooting(or a relative link) so the zh “Getting Help” section doesn’t send users to a 404.
packages/docs/content/zh/manual/features/mod-loaders.mdx:119 - Same issue here:
../development/implementation.mdx#...resolves to/docs/manual/development/...from this page and will 404, and.mdxshouldn’t be in the route. Please use../../development/implementation#版本合并机制(or an equivalent correct route).
packages/docs/content/zh/development/index.mdx:267 - 该段落以 “TypeScript/Svelte” 为标题并讲解 Svelte 5 runes，但当前 UI 技术栈已是 React。建议将标题与示例改为 React + Zustand 的实际约定（或明确标注为迁移前历史说明）。
packages/docs/content/zh/manual/features/mod-loaders.mdx:100 - This link uses
../development/implementation.mdx#..., which from/docs/manual/features/mod-loadersresolves to/docs/manual/development/...and will 404, and it also includes the.mdxextension. Please update to the correct path like../../development/implementation#核心库解析.
packages/docs/content/zh/manual/getting-started.mdx:122 - This links to
/docs/manual/features/instances, but there is nocontent/zh/manual/features/instances.mdx(and it’s not inmeta.json). This will be a broken link unless an Instances page is added or the link is adjusted to an existing page.
packages/docs/content/zh/manual/features/mod-loaders.mdx:226 - This (and the other links below it) use
../development/implementation.mdx#..., which from/docs/manual/features/...resolves under/docs/manual/development/...and will 404; it also includes.mdx. Please update these links to../../development/implementation#...(no extension) so they correctly resolve to/docs/development/implementation.
packages/docs/content/zh/manual/features/java.mdx:160 - This link uses
../development/implementation.mdx#..., which from/docs/manual/features/javaresolves to/docs/manual/development/...and will 404, and it also includes the.mdxextension. Please change to../../development/implementation#参数优化与-jvm-配置(no.mdx) so it resolves correctly.
| "libraries": [...] | ||
| } | ||
| ``` | ||
| DropOut integrates with the Fabric Meta API to automatically fetch compatible loader versions. In the background, it generates the version JSON, handles library dependencies, and utilizes the inheritance system to ensure perfect compatibility with vanilla Minecraft. Detailed JSON structure can be found in [Technical Details](/docs/development/implementation#fabric-integration). |
There was a problem hiding this comment.
This link is absolute (/docs/development/implementation#...), so when reading the EN site under /en/... it will jump to the default-locale (zh) page. Prefer relative links (so locale is preserved), e.g. ../development/implementation#fabric-integration.
Suggested change
| DropOut integrates with the Fabric Meta API to automatically fetch compatible loader versions. In the background, it generates the version JSON, handles library dependencies, and utilizes the inheritance system to ensure perfect compatibility with vanilla Minecraft. Detailed JSON structure can be found in [Technical Details](/docs/development/implementation#fabric-integration). | |
| DropOut integrates with the Fabric Meta API to automatically fetch compatible loader versions. In the background, it generates the version JSON, handles library dependencies, and utilizes the inheritance system to ensure perfect compatibility with vanilla Minecraft. Detailed JSON structure can be found in [Technical Details](../development/implementation#fabric-integration). |
| { | ||
| type: 'main', | ||
| text: locale === 'zh' ? '开发文档' : 'Development', | ||
| url: `${localePrefix}/docs/development`, |
There was a problem hiding this comment.
This nav link points to ${localePrefix}/docs/development, but the EN development section currently has no content/en/development/index.mdx. Consider linking to an existing page (e.g. /docs/development/guide) or adding an EN development index page so /en/docs/development doesn’t 404.
Suggested change
| url: `${localePrefix}/docs/development`, | |
| url: `${localePrefix}/docs/development/guide`, |
| className="bg-fd-secondary hover:bg-fd-secondary/80 text-fd-secondary-foreground font-semibold rounded-lg px-6 py-3 transition-colors cursor-pointer" | ||
| href={`${localePrefix}/docs/features`} | ||
| className="bg-fd-secondary hover:bg-fd-secondary/80 text-fd-secondary-foreground font-semibold rounded-lg px-6 py-3 transition-colors cursor-pointer border border-blue-600/50" | ||
| href={`${localePrefix}/docs/development`} |
There was a problem hiding this comment.
The CTA uses ${localePrefix}/docs/development, but the EN docs tree currently doesn’t have a content/en/development/index.mdx entry page, so /en/docs/development may 404. Consider linking directly to an existing page like ${localePrefix}/docs/development/guide or adding a development index page for EN.
Suggested change
| href={`${localePrefix}/docs/development`} | |
| href={`${localePrefix}/docs/development/guide`} |
Comment on lines
+24
to
+27
| Account data is persisted in `accounts.json`, containing account type and encrypted token information: | ||
| ```json | ||
| { | ||
| "active_account_uuid": "...", |
There was a problem hiding this comment.
This section says accounts.json contains “encrypted token information” and uses active_account_uuid, but the current implementation persists plaintext JSON with active_account_id (see src-tauri/src/core/account_storage.rs). Please update the wording and JSON example to match the actual store format; if encryption is planned, mention it as future work.
Suggested change
| Account data is persisted in `accounts.json`, containing account type and encrypted token information: | |
| ```json | |
| { | |
| "active_account_uuid": "...", | |
| Account data is persisted in `accounts.json`, containing account type and token information in plaintext (encryption at rest is planned for a future version): | |
| ```json | |
| { | |
| "active_account_id": "...", |
|
|
||
| ### 账户存储 | ||
|
|
||
| 账户数据存储在应用文件夹的 `accounts.json` 中。该文件包含已登录账户的加密令牌、过期时间和基本的个人资料信息。 |
There was a problem hiding this comment.
The docs currently state accounts.json contains “加密令牌”, but the implementation writes tokens in plaintext JSON (see core/account_storage.rs). Please adjust the wording to avoid implying encryption; if encryption is planned, call it out explicitly as a future improvement.
Suggested change
| 账户数据存储在应用文件夹的 `accounts.json` 中。该文件包含已登录账户的加密令牌、过期时间和基本的个人资料信息。 | |
| 账户数据存储在应用文件夹的 `accounts.json` 中。该文件包含已登录账户的访问令牌（目前以明文 JSON 存储）、过期时间和基本的个人资料信息；后续版本会考虑增加本地加密以提升安全性。 |
Comment on lines
+141
to
142
| DropOut's launch engine automatically handles this complex merging of libraries, arguments, and assets. Detailed merging logic and code implementation can be viewed in [Implementation Details: Version Merging](../development/implementation.mdx#version-merging-mechanism). | ||
|
|
There was a problem hiding this comment.
This link has the same issue: ../development/implementation.mdx#... resolves under /docs/features/development/... and includes .mdx. Please change to ../../development/implementation#version-merging-mechanism so it routes correctly (and preserves locale).
Comment on lines
+14
to
+15
| // 其他语言重定向到 /:lang/docs/manual/getting-started | ||
| return redirect(`/${lang}/docs/manual/getting-started`); |
There was a problem hiding this comment.
This redirect always targets /docs/manual/getting-started. The EN content tree currently doesn’t have an en/manual/getting-started page, so /en/docs/manual/getting-started will 404. Either add the EN manual section or redirect non-default locales to the actual EN entrypoint (e.g. /${lang}/docs/getting-started).
Suggested change
| // 其他语言重定向到 /:lang/docs/manual/getting-started | |
| return redirect(`/${lang}/docs/manual/getting-started`); | |
| // 其他语言重定向到 /:lang/docs/getting-started（本地化入口） | |
| return redirect(`/${lang}/docs/getting-started`); |
| text: locale === 'zh' ? '文档' : 'Documentation', | ||
| url: `${localePrefix}/docs`, | ||
| text: locale === 'zh' ? '使用文档' : 'Manual', | ||
| url: `${localePrefix}/docs/manual`, |
There was a problem hiding this comment.
This nav link points to ${localePrefix}/docs/manual, but the EN docs content currently doesn’t include a content/en/manual section. Unless EN manual pages are added, /en/docs/manual will 404; consider linking to an existing EN entry page (e.g. /docs/getting-started) or adding content/en/manual/index.mdx.
Suggested change
| url: `${localePrefix}/docs/manual`, | |
| url: locale === 'zh' ? `${localePrefix}/docs/manual` : `${localePrefix}/docs/getting-started`, |
Comment on lines
+120
to
124
| <Card | ||
| title="Features" | ||
| href="/docs/manual/features" | ||
| description="Learn about all the features DropOut offers" | ||
| /> |
There was a problem hiding this comment.
These “Next Steps” links point into /docs/manual/..., but the EN content tree doesn’t include a content/en/manual section. Unless EN manual pages are added, these links will 404 under /en/.... Either create the EN manual section or update these hrefs back to existing EN routes.
packages/docs/app/docs/page.tsx
Outdated
Comment on lines
48
to
52
| Card: (props: any) => ( | ||
| <Card | ||
| {...props} | ||
| className={`border-blue-600/20 hover:border-blue-600/50 transition-colors ${props.className || ''}`} | ||
| /> |
There was a problem hiding this comment.
Using props: any here loses type-safety and may violate Biome’s recommended TS lint rules. Consider typing this as React.ComponentProps<typeof Card> (or the exported Card props type) so consumers get correct prop checking and autocomplete.
NtskwK
force-pushed
the
refactor/docs
branch
from
029d906 to
17e18b1
Compare
HsiangNianian
approved these changes
Feb 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
Documentation: