From 81a62402ef6f8900ff092366121a9b7a4263ba52 Mon Sep 17 00:00:00 2001 From: Natsuu 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: 简律纯 --- packages/docs/app/components/mermaid.tsx | 29 +++++++++++++++++++++++++++++ packages/docs/app/docs/page.tsx | 30 ++++++++++++++++++++++-------- packages/docs/app/lib/layout.shared.tsx | 9 +++++++-- packages/docs/app/lib/source.ts | 4 ++-- packages/docs/app/routes/docs.tsx | 8 ++++---- packages/docs/app/routes/home.tsx | 14 +++++++------- 6 files changed, 71 insertions(+), 23 deletions(-) create mode 100644 packages/docs/app/components/mermaid.tsx (limited to 'packages/docs/app') diff --git a/packages/docs/app/components/mermaid.tsx b/packages/docs/app/components/mermaid.tsx new file mode 100644 index 0000000..bb25f2d --- /dev/null +++ b/packages/docs/app/components/mermaid.tsx @@ -0,0 +1,29 @@ +'use client'; + +import { useEffect, useRef } from 'react'; +import mermaid from 'mermaid'; + +mermaid.initialize({ + startOnLoad: false, + theme: 'default', +}); + +export function Mermaid({ chart }: { chart: string }) { + const ref = useRef(null); + + useEffect(() => { + if (ref.current) { + mermaid.run({ + nodes: [ref.current], + }); + } + }, [chart]); + + return ( +
+
+ {chart} +
+
+ ); +} diff --git a/packages/docs/app/docs/page.tsx b/packages/docs/app/docs/page.tsx index a9e3433..49ad005 100644 --- a/packages/docs/app/docs/page.tsx +++ b/packages/docs/app/docs/page.tsx @@ -8,20 +8,21 @@ import { i18n } from '@/lib/i18n'; import { baseOptions } from '@/lib/layout.shared'; import { useFumadocsLoader } from 'fumadocs-core/source/client'; import browserCollections from 'fumadocs-mdx:collections/browser'; +import { Mermaid } from '@/components/mermaid'; export async function loader({ params }: Route.LoaderArgs) { // 从路由参数获取语言，如果没有则使用默认语言 - // URL 格式: /docs/getting-started (默认语言 zh) - // URL 格式: /en/docs/getting-started (英语) + // URL 格式: /docs/manual/getting-started (默认语言 zh) + // URL 格式: /en/docs/manual/getting-started (英语) const lang = (params.lang && i18n.languages.includes(params.lang as any)) ? (params.lang as 'zh' | 'en') : (i18n.defaultLanguage as 'zh' | 'en'); - + // 获取文档路径 slugs const slugs = params['*']?.split('/').filter((v) => v.length > 0) || []; - + const page = source.getPage(slugs, lang); - + if (!page) { throw new Response('Not found', { status: 404 }); } @@ -37,10 +38,23 @@ const clientLoader = browserCollections.docs.createClientLoader({ component({ toc, frontmatter, default: Mdx }) { return ( - {frontmatter.title} - {frontmatter.description} + {/* 老王说不要这个 */} + {/* {frontmatter.title} + {frontmatter.description} */} - + ) => ( + + ), + Cards, + Mermaid + }} + /> ); diff --git a/packages/docs/app/lib/layout.shared.tsx b/packages/docs/app/lib/layout.shared.tsx index 6e90ba0..b3595eb 100644 --- a/packages/docs/app/lib/layout.shared.tsx +++ b/packages/docs/app/lib/layout.shared.tsx @@ -16,8 +16,13 @@ export function baseOptions(locale: string): BaseLayoutProps { links: [ { type: 'main', - text: locale === 'zh' ? '文档' : 'Documentation', - url: `${localePrefix}/docs`, + text: locale === 'zh' ? '使用文档' : 'Manual', + url: `${localePrefix}/docs/manual`, + }, + { + type: 'main', + text: locale === 'zh' ? '开发文档' : 'Development', + url: `${localePrefix}/docs/development`, }, ], }; diff --git a/packages/docs/app/lib/source.ts b/packages/docs/app/lib/source.ts index bce9bf9..4d6cc3a 100644 --- a/packages/docs/app/lib/source.ts +++ b/packages/docs/app/lib/source.ts @@ -7,6 +7,6 @@ export const source = loader({ baseUrl: '/docs', i18n, // hideLocale: 'default-locale' 会自动生成正确的 URL: - // - 默认语言 (zh): /docs/getting-started - // - 其他语言 (en): /en/docs/getting-started + // - 默认语言 (zh): /docs/manual/getting-started + // - 其他语言 (en): /en/docs/manual/getting-started }); diff --git a/packages/docs/app/routes/docs.tsx b/packages/docs/app/routes/docs.tsx index 5154d27..5090ccf 100644 --- a/packages/docs/app/routes/docs.tsx +++ b/packages/docs/app/routes/docs.tsx @@ -6,11 +6,11 @@ import { i18n } from '@/lib/i18n'; export function loader({ params }: Route.LoaderArgs) { const lang = params.lang as string | undefined; - // 如果没有语言参数或是默认语言，重定向到 /docs/getting-started + // 如果没有语言参数或是默认语言，重定向到 /docs/manual/getting-started if (!lang || lang === i18n.defaultLanguage) { - return redirect('/docs/getting-started'); + return redirect('/docs/manual/getting-started'); } - // 其他语言重定向到 /:lang/docs/getting-started - return redirect(`/${lang}/docs/getting-started`); + // 其他语言重定向到 /:lang/docs/manual/getting-started + return redirect(`/${lang}/docs/manual/getting-started`); } diff --git a/packages/docs/app/routes/home.tsx b/packages/docs/app/routes/home.tsx index 66b5333..427bf4e 100644 --- a/packages/docs/app/routes/home.tsx +++ b/packages/docs/app/routes/home.tsx @@ -10,7 +10,7 @@ const texts = { subtitle: 'Modern. Reproducible. Developer-Grade.', description: 'Built with Tauri v2 and Rust for native performance and minimal resource usage', start: 'Get Started', - features: 'Features', + development: 'Development', }, features: { items: [ @@ -42,7 +42,7 @@ const texts = { subtitle: '现代、可复现、开发者级', description: '基于 Tauri v2 和 Rust 构建，拥有原生性能和极低的资源占用', start: '开始使用', - features: '功能特性', + development: '参与开发', }, features: { items: [ @@ -107,10 +107,10 @@ export default function Home({ params }: Route.ComponentProps) { {t.hero.start} - {t.hero.features} + {t.hero.development} @@ -129,7 +129,7 @@ export default function Home({ params }: Route.ComponentProps) { {/* Features Grid */}
{t.features.items.map((item, i) => ( -
+

{item.title}

{item.desc} @@ -162,7 +162,7 @@ export default function Home({ params }: Route.ComponentProps) {

{t.cta.button} -- cgit v1.2.3-70-g09d2