feat: improve and refactor the site

Signed-off-by: bitliu <[email protected]>

Author: Xunzhuo

.gitignore

@@ -97,4 +97,5 @@ example_prd.txt
 scripts/prd.txt
 .env.taskmaster
 package-lock.json
-package.json
+
+website/build

Makefile

@@ -155,3 +155,24 @@ download-models:
 	@if [ ! -d "models/pii_classifier_modernbert_base_presidio_token_model" ]; then \
 		hf download LLM-Semantic-Router/pii_classifier_modernbert-base_presidio_token_model --local-dir models/pii_classifier_modernbert-base_presidio_token_model; \
 	fi
+
+# Documentation targets
+docs-install:
+	@echo "Installing documentation dependencies..."
+	cd website && npm install
+
+docs-dev: docs-install
+	@echo "Starting documentation development server..."
+	cd website && npm start
+
+docs-build: docs-install
+	@echo "Building documentation for production..."
+	cd website && npm run build
+
+docs-serve: docs-build
+	@echo "Serving production documentation..."
+	cd website && npm run serve
+
+docs-clean:
+	@echo "Cleaning documentation build artifacts..."
+	cd website && npm run clear

mkdocs.yml

@@ -0,0 +1,112 @@
+# 技术方案设计
+
+## 技术架构
+
+### 核心技术栈
+- **Docusaurus 3.x**: 现代化的静态网站生成器
+- **React 18**: 用于自定义组件和页面
+- **TypeScript**: 提供类型安全
+- **MDX**: 支持在 Markdown 中使用 React 组件
+- **Mermaid**: 图表渲染支持
+- **Algolia DocSearch**: 搜索功能（可选）
+
+### 项目结构
+```
+website/
+├── docusaurus.config.js     # Docusaurus 配置
+├── sidebars.js             # 侧边栏配置
+├── package.json            # 依赖管理
+├── src/
+│   ├── components/         # 自定义 React 组件
+│   ├── css/               # 自定义样式
+│   ├── pages/             # 自定义页面
+│   └── theme/             # 主题自定义
+├── docs/                  # 文档内容（迁移自现有 docs/）
+├── static/                # 静态资源
+└── build/                 # 构建输出
+```
+
+### 科技感设计方案
+
+#### 配色方案
+- **主色调**: 深蓝色系 (#0D1117, #161B22, #21262D)
+- **强调色**: 霓虹蓝 (#58A6FF), 霓虹绿 (#7C3AED)
+- **文本色**: 高对比度白色和灰色
+- **代码块**: 暗色主题配合语法高亮
+
+#### 视觉效果
+- **渐变背景**: 深色渐变背景
+- **毛玻璃效果**: 导航栏和卡片组件
+- **动画效果**: 页面切换和悬停动画
+- **图标系统**: 现代化的 Feather Icons 或 Heroicons
+
+#### 自定义组件
+- **Hero Section**: 带动画的首页展示区域
+- **Feature Cards**: 功能特性展示卡片
+- **Code Playground**: 交互式代码示例
+- **Architecture Diagram**: 增强的架构图展示
+
+### 迁移策略
+
+#### 内容迁移
+1. **文档结构映射**:
+   - `docs/index.md` → `docs/intro.md`
+   - 保持现有的文件夹结构
+   - 更新内部链接格式
+
+2. **导航配置**:
+   - 将 `mkdocs.yml` 的 nav 配置转换为 `sidebars.js`
+   - 保持相同的层级结构
+
+3. **资源迁移**:
+   - 图片文件移动到 `static/img/`
+   - 更新图片引用路径
+
+#### 功能增强
+1. **Mermaid 集成**: 使用 `@docusaurus/theme-mermaid` 插件
+2. **代码高亮**: 配置 Prism 主题和语言支持
+3. **搜索功能**: 集成本地搜索或 Algolia DocSearch
+4. **PWA 支持**: 离线访问和安装功能
+
+### 构建和部署
+
+#### 开发环境
+- `npm start`: 启动开发服务器
+- `npm run build`: 构建生产版本
+- `npm run serve`: 预览生产版本
+
+#### Makefile 集成
+```makefile
+# 文档相关命令
+docs-install:
+	cd website && npm install
+
+docs-dev: docs-install
+	cd website && npm start
+
+docs-build: docs-install
+	cd website && npm run build
+
+docs-serve: docs-build
+	cd website && npm run serve
+```
+
+### 性能优化
+
+#### 构建优化
+- **代码分割**: 自动的路由级代码分割
+- **图片优化**: 自动图片压缩和 WebP 转换
+- **CSS 优化**: 自动 CSS 压缩和去重
+- **预加载**: 关键资源预加载
+
+#### 运行时优化
+- **懒加载**: 图片和组件懒加载
+- **缓存策略**: 静态资源长期缓存
+- **CDN 支持**: 静态资源 CDN 分发
+
+### 安全性考虑
+
+- **内容安全策略**: 配置 CSP 头部
+- **XSS 防护**: MDX 内容安全渲染
+- **依赖安全**: 定期更新依赖包
+- **构建安全**: 构建过程中的安全检查

specs/docusaurus_migration/design.md

@@ -0,0 +1,53 @@
+# 需求文档
+
+## 介绍
+
+将现有的基于 MkDocs 的文档系统重构为基于 Docusaurus 的现代化文档网站，提供极具科技感的视觉体验和本地预览功能。
+
+## 需求
+
+### 需求 1 - Docusaurus 文档系统迁移
+
+**用户故事：** 作为开发者，我希望将现有的 MkDocs 文档迁移到 Docusaurus，以获得更现代化的文档体验和更好的维护性。
+
+#### 验收标准
+
+1. When 执行文档构建命令时，系统应当成功生成基于 Docusaurus 的静态网站
+2. When 访问文档网站时，系统应当展示所有现有的文档内容，包括 API 参考、架构说明、训练指南等
+3. When 浏览文档时，系统应当保持原有的导航结构和内容组织方式
+4. When 查看 Mermaid 图表时，系统应当正确渲染所有现有的架构图和流程图
+
+### 需求 2 - 科技感视觉设计
+
+**用户故事：** 作为用户，我希望文档网站具有极具科技感的视觉风格，提供现代化的用户体验。
+
+#### 验收标准
+
+1. When 访问网站时，系统应当展示深色主题为主的科技感配色方案
+2. When 浏览页面时，系统应当提供流畅的动画效果和现代化的 UI 组件
+3. When 查看代码块时，系统应当使用语法高亮和现代化的代码展示样式
+4. When 使用导航时，系统应当提供直观的侧边栏和顶部导航体验
+5. When 在移动设备上访问时，系统应当提供响应式的移动端体验
+
+### 需求 3 - 本地预览功能
+
+**用户故事：** 作为开发者，我希望通过 Makefile 命令轻松启动本地文档预览服务。
+
+#### 验收标准
+
+1. When 执行 `make docs-dev` 时，系统应当启动本地开发服务器并自动打开浏览器
+2. When 修改文档内容时，系统应当自动重新加载页面显示最新内容
+3. When 执行 `make docs-build` 时，系统应当构建生产版本的静态文件
+4. When 执行 `make docs-serve` 时，系统应当启动生产版本的本地预览服务
+
+### 需求 4 - 内容增强
+
+**用户故事：** 作为用户，我希望文档网站提供增强的内容展示功能，提升阅读体验。
+
+#### 验收标准
+
+1. When 查看 API 文档时，系统应当提供交互式的 API 示例和代码片段
+2. When 浏览架构文档时，系统应当支持可交互的 Mermaid 图表
+3. When 搜索内容时，系统应当提供快速准确的全文搜索功能
+4. When 查看代码示例时，系统应当提供一键复制功能
+5. When 浏览长文档时，系统应当提供目录导航和回到顶部功能

specs/docusaurus_migration/requirements.md

@@ -0,0 +1,108 @@
+# 实施计划
+
+## 阶段 1: 项目初始化和基础配置
+
+- [ ] 1. 创建 Docusaurus 项目结构
+  - 在项目根目录创建 `website/` 文件夹
+  - 初始化 Docusaurus 项目
+  - 配置基础的 `docusaurus.config.js`
+  - 设置 `package.json` 和依赖管理
+  - _需求: 需求1_
+
+- [ ] 2. 配置科技感主题和样式
+  - 创建自定义 CSS 文件，实现深色科技感配色
+  - 配置 Prism 代码高亮主题
+  - 设置自定义字体和图标系统
+  - 实现毛玻璃效果和渐变背景
+  - _需求: 需求2_
+
+- [ ] 3. 设置 Mermaid 图表支持
+  - 安装和配置 `@docusaurus/theme-mermaid` 插件
+  - 测试现有 Mermaid 图表的渲染效果
+  - 优化图表在深色主题下的显示效果
+  - _需求: 需求1, 需求2_
+
+## 阶段 2: 内容迁移和结构配置
+
+- [ ] 4. 迁移文档内容
+  - 将 `docs/` 目录下的所有 Markdown 文件复制到 `website/docs/`
+  - 更新文件内的图片链接路径
+  - 调整内部文档链接格式以适配 Docusaurus
+  - 迁移静态资源到 `website/static/` 目录
+  - _需求: 需求1_
+
+- [ ] 5. 配置导航和侧边栏
+  - 根据 `mkdocs.yml` 的导航配置创建 `sidebars.js`
+  - 保持原有的文档层级结构
+  - 配置顶部导航栏
+  - 设置文档分类和标签
+  - _需求: 需求1_
+
+- [ ] 6. 创建增强的首页
+  - 设计科技感的 Hero Section
+  - 创建功能特性展示卡片
+  - 添加动画效果和交互元素
+  - 集成项目统计和徽章
+  - _需求: 需求2, 需求4_
+
+## 阶段 3: 功能增强和组件开发
+
+- [ ] 7. 开发自定义组件
+  - 创建交互式代码示例组件
+  - 开发 API 文档展示组件
+  - 实现架构图增强展示组件
+  - 添加一键复制代码功能
+  - _需求: 需求4_
+
+- [ ] 8. 集成搜索功能
+  - 配置本地搜索插件
+  - 优化搜索结果展示
+  - 添加搜索快捷键支持
+  - 测试搜索功能的准确性
+  - _需求: 需求4_
+
+- [ ] 9. 实现响应式设计
+  - 优化移动端显示效果
+  - 调整平板设备的布局
+  - 测试不同屏幕尺寸的兼容性
+  - 优化触摸交互体验
+  - _需求: 需求2_
+
+## 阶段 4: 构建系统和部署配置
+
+- [ ] 10. 配置构建系统
+  - 优化 Webpack 构建配置
+  - 设置代码分割和懒加载
+  - 配置图片优化和压缩
+  - 实现 PWA 功能支持
+  - _需求: 需求3_
+
+- [ ] 11. 集成 Makefile 命令
+  - 在 `Makefile` 中添加文档相关的命令
+  - 实现 `make docs-dev` 开发服务器启动
+  - 实现 `make docs-build` 生产构建
+  - 实现 `make docs-serve` 本地预览服务
+  - _需求: 需求3_
+
+- [ ] 12. 性能优化和测试
+  - 进行构建性能优化
+  - 测试页面加载速度
+  - 验证所有功能的正常工作
+  - 进行跨浏览器兼容性测试
+  - _需求: 需求1, 需求2, 需求3, 需求4_
+
+## 阶段 5: 文档完善和验收
+
+- [ ] 13. 完善文档内容
+  - 检查所有迁移内容的完整性
+  - 修复可能的格式问题
+  - 优化代码示例的展示
+  - 添加缺失的文档链接
+  - _需求: 需求1, 需求4_
+
+- [ ] 14. 最终测试和验收
+  - 进行完整的功能测试
+  - 验证所有验收标准
+  - 性能基准测试
+  - 用户体验测试
+  - _需求: 需求1, 需求2, 需求3, 需求4_

specs/docusaurus_migration/tasks.md

@@ -0,0 +1,5 @@
+This folder stores temp files that Docusaurus' client bundler accesses.
+
+DO NOT hand-modify files in this folder because they will be overwritten in the
+next build. You can clear all build artifacts (including this folder) with the
+`docusaurus clear` command.