代码架构

Docusaurus 预设

站点使用 @docusaurus/preset-classic，一次启用 docs、blog、theme 三大能力：

自定义首页

文件	作用
src/pages/index.tsx	首页布局，Hero 区 + 「开始阅读文档」按钮链至 /docs/intro
src/components/HomepageFeatures/	首页特性展示区块
src/pages/index.module.css	首页样式

首页不走 docs/ 插件，路由固定为 /。

主题与样式

• 默认 Docusaurus classic 主题
• colorMode.respectPrefersColorScheme: true — 跟随系统深浅色
• Prism 代码高亮：亮色 github，暗色 dracula
• Mermaid 通过 @docusaurus/theme-mermaid 在 Markdown 中启用

国际化架构

• 文档正文以中文为主，存放在 docs/
• 英文翻译可放在 i18n/en/docusaurus-plugin-content-docs/current/ 镜像路径
• 运行 npm run write-translations 可提取待翻译字符串

文档版本

• versions.json 声明可用版本
• docusaurus.config.ts 中 docs.versions 配置 current 与 v1 标签
• 导航栏 docsVersionDropdown 供读者切换

扩展点

需求	修改位置
站点标题、footer、navbar	docusaurus.config.ts → themeConfig
新增文档分类	sidebars.ts
全局样式	src/css/custom.css
自定义 landing	src/pages/
部署目标	wrangler.jsonc + package.json scripts

类型检查

项目含 tsconfig.json，配置与 sidebar 使用 TypeScript。提交前建议：

npm run typecheck