7.9 KiB
7.9 KiB
CodeDocs 升级总结与实施指南
📋 已完成的升级
1️⃣ 首页样式升级 ✅
变更清单
-
HomepageFeatures.tsx:
- 从 3 个简单文本卡片 → 交互式卡片组件
- 支持图标、颜色、渐变背景
- 完整的 hover 动效和动画
-
HomepageFeatures.module.css:
- 新增蓝色悬停动效 (
hover:text-primary) - 新增图标背景色变化
- 新增箭头滑出动画
- 新增卡片缩放 + 投影效果
- 新增分层渐变背景
- 响应式网格布局（3列→1列）
- 新增蓝色悬停动效 (
-
index.tsx:
- 新增 3 个主要导航按钮
- 优化首页文案
- 增强视觉层级
设计理念（参考 dyte-io/docs）
卡片组成 = icon + title + description + hover-effect
├── Icon: 根据分类变色（蓝色/青色/粉色）
├── Title: hover 时变为主色 (#2160fd)
├── Border: hover 时从半透明→主色
└── Arrow: hover 时从隐藏→显示并滑入
2️⃣ 多级菜单配置 ✅
变更清单
- docusaurus.config.ts - navbar.items:
items: [
// 技术文档 - 3 级分类
{
type: 'dropdown',
label: '📚 技术文档',
items: [
'⚙️ 后端技术',
'⚛️ 前端开发',
'🧠 算法与面试'
]
},
// 工具与资源 - 预留扩展
{
type: 'dropdown',
label: '🛠️ 工具与资源',
items: [
'📖 最佳实践',
'🔗 常用链接',
'📚 推荐阅读'
]
},
// 其他链接
'📝 Blog',
'GitHub'
]
菜单截图预期
顶部导航：
[📚 技术文档 ▼] [🛠️ 工具与资源 ▼] [📝 Blog] [GitHub]
下拉展开：
📚 技术文档 ▼
├─ ⚙️ 后端技术
├─ ⚛️ 前端开发
└─ 🧠 算法与面试
3️⃣ 样式系统升级 ✅
变更清单
-
tailwind.config.js: 新建
- 蓝色色系定义 (#2160fd)
- 青色色系支持
- 粉色色系支持
- 响应式断点优化
-
postcss.config.js: 新建
- PostCSS 处理管道配置
-
custom.css: 重写
- 原有 Infima 主色替换为蓝色 (#2160fd)
- 增加 Tailwind 导入（@import）
- 新增 CSS 变量系统（支持深色模式）
- 新增 hero 背景渐变
颜色对照表
| 用途 | 颜色 | 十六进制 | RGB |
|---|---|---|---|
| 主色 (Primary) | 蓝色 | #2160fd | rgb(33 96 253) |
| 悬停强调 | 深蓝 | #1850d8 | - |
| 次色 (Secondary) | 青色 | #06b6d4 | - |
| 三色 (Tertiary) | 粉色 | #ec4899 | - |
4️⃣ 内容架构规划 ✅
文档位置
ARCHITECTURE_PLAN.md- 完整规划书
结构概览
一级菜单 (4 类)
├─ 📚 技术文档
│ ├─ ⚙️ 后端技术 (Java/Spring/Database/MQ/分布式)
│ ├─ ⚛️ 前端开发 (React/Vue/工程化/跨端)
│ └─ 🧠 算法与面试 (数据结构/算法/系统设计)
├─ 🛠️ 工具与资源 (best practices/links/reading)
├─ 📝 Blog (分享与资讯)
└─ GitHub (开源)
内容分级（学习路径）
- 快速入门 (⏱️ 5-10 分钟) - 适合初学
- 深度学习 (⏱️ 30 分钟-1 小时) - 详解原理
- 性能优化 (⏱️ 1-2 小时) - 高级技巧
- 面试突破 (⏱️ 灵活) - 频考题
🚀 下一步操作
步骤 1: 本地验证 (NOW)
cd /opt/cyy/code-docs
# 若未完成 npm install，先安装依赖
npm install
# 启动开发服务器
npm start
# 验证内容：
# ✅ 首页 3 个卡片是否显示
# ✅ 卡片 hover 是否有蓝色效果
# ✅ 菜单是否显示下拉箭头
# ✅ 深色模式是否正常
步骤 2: 迁移现有内容 (Week 1)
当前文件：
docs/
├─ intro-docs.mdx ✅ 保留
├─ backend-doc/ ✅ 已有结构
├─ frontend-doc/ ✅ 已有结构
├─ LeetCode/ ✅ 已有结构
└─ ...
需要处理：
1. 更新 sidebars.ts 以支持新菜单
2. 验证所有链接有效性
3. 补充缺失的 intro-docs.md 文件
步骤 3: 菜单链接修复 (Week 1)
在 navbar 中验证以下路由存在：
/docs/backend-doc/intro-docs/docs/frontend-doc/intro-docs/docs/LeetCode/intro-docs
步骤 4: 内容扩充计划 (Phase 2)
根据 ARCHITECTURE_PLAN.md 逐步添加：
高优先级:
- Spring Framework 核心（5-8 篇）
- React Hooks 深入（3-5 篇）
- LeetCode 精选题库（10-15 题）
中优先级:
- JVM 调优系列
- Vue 3 完整指南
- 系统设计案例
低优先级:
- 最佳实践合集
- 工具对比
- 推荐书籍
🎨 设计效果预览
首页卡片效果
┌─────────────────────────────────┐
│ [⚙️] 后端技术 │ → hover: border-blue, text-blue, arrow-in
│ │
│ 深度讲解 Spring Boot / Spring │
│ Cloud 核心概念、最佳实践... │
│ │
│ → │ (animated)
└─────────────────────────────────┘
动效细节：
- 渐变背景从灰→蓝色渐变
- 图标放大 10%，背景变蓝
- 标题变成蓝色 (#2160fd)
- 箭头从右侧滑入
- 整体卡片上移 4px
- 投影增强，显示深度感
顶部菜单效果
┌─ CodeDocs ─────┐ [📚 技术文档 ▼] [🛠️ 工具 ▼] [📝 Blog] [GitHub]
↓
┌─────────────┐
│ ⚙️ 后端 │
│ ⚛️ 前端 │
│ 🧠 算法 │
└─────────────┘
📊 检查清单
- npm install 完成
- npm start 本地验证通过
- 首页卡片显示正常
- 卡片 hover 效果生效
- 菜单下拉正常
- 所有链接有效
- 深色模式测试
- 响应式（手机端）测试
📁 文件变更总结
| 文件 | 操作 | 说明 |
|---|---|---|
src/components/HomepageFeatures.tsx |
✏️ 修改 | 新组件结构 + 3 色卡片 |
src/components/HomepageFeatures.module.css |
✏️ 重写 | 完整的悬停动效 |
src/pages/index.tsx |
✏️ 修改 | 新的 CTA 按钮 |
src/css/custom.css |
✏️ 重写 | 主色改蓝 + Tailwind 导入 |
docusaurus.config.ts |
✏️ 修改 | 多级菜单配置 |
tailwind.config.js |
✨ 新建 | Tailwind 配置 |
postcss.config.js |
✨ 新建 | PostCSS 管道 |
package.json |
✏️ 修改 | 已升级依赖版本 |
ARCHITECTURE_PLAN.md |
✨ 新建 | 内容架构规划 |
🆘 常见问题
Q1: npm install 很慢？
A: 使用 pnpm 或 npm 阿里镜像加速
npm install -g pnpm
pnpm install
Q2: Tailwind 样式未生效？
A: 需要先完成 npm install，再运行 npm start
Q3: 首页链接 404？
A: 检查 /docs 下是否存在对应的文件夹：
ls -la docs/
# 应该看到：backend-doc/ frontend-doc/ LeetCode/
Q4: 深色模式图标不清晰？
A: 在 custom.css 中针对 [data-theme='dark'] 添加 color 覆盖
📞 后续支持
需要进一步升级：
- 搜索优化 - 集成 Algolia 优化查询
- 版本管理 - 为 SDK 文档添加版本切换（参考 dyte-io/docs）
- API 文档 - 集成 OpenAPI / Swagger
- 交互示例 - 嵌入 CodeSandbox / RunKit
- 反馈系统 - 页面评分与问题报告
参考资源
最后更新: 2026-05-06
更新者: CodeDocs 升级系统
版本: v2.0