311 lines
7.9 KiB
Markdown
311 lines
7.9 KiB
Markdown
# 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**:
|
||
|
||
```typescript
|
||
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 (开源)
|
||
```
|
||
|
||
#### 内容分级（学习路径）
|
||
1. **快速入门** (⏱️ 5-10 分钟) - 适合初学
|
||
2. **深度学习** (⏱️ 30 分钟-1 小时) - 详解原理
|
||
3. **性能优化** (⏱️ 1-2 小时) - 高级技巧
|
||
4. **面试突破** (⏱️ 灵活) - 频考题
|
||
|
||
---
|
||
|
||
## 🚀 下一步操作
|
||
|
||
### 步骤 1: 本地验证 (NOW)
|
||
```bash
|
||
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 阿里镜像加速
|
||
```bash
|
||
npm install -g pnpm
|
||
pnpm install
|
||
```
|
||
|
||
### Q2: Tailwind 样式未生效？
|
||
**A**: 需要先完成 `npm install`，再运行 `npm start`
|
||
|
||
### Q3: 首页链接 404？
|
||
**A**: 检查 `/docs` 下是否存在对应的文件夹：
|
||
```bash
|
||
ls -la docs/
|
||
# 应该看到：backend-doc/ frontend-doc/ LeetCode/
|
||
```
|
||
|
||
### Q4: 深色模式图标不清晰？
|
||
**A**: 在 custom.css 中针对 `[data-theme='dark']` 添加 color 覆盖
|
||
|
||
---
|
||
|
||
## 📞 后续支持
|
||
|
||
需要进一步升级：
|
||
1. **搜索优化** - 集成 Algolia 优化查询
|
||
2. **版本管理** - 为 SDK 文档添加版本切换（参考 dyte-io/docs）
|
||
3. **API 文档** - 集成 OpenAPI / Swagger
|
||
4. **交互示例** - 嵌入 CodeSandbox / RunKit
|
||
5. **反馈系统** - 页面评分与问题报告
|
||
|
||
---
|
||
|
||
## 参考资源
|
||
|
||
- 📖 [Docusaurus 官方文档](https://docusaurus.io/)
|
||
- 🎨 [Tailwind CSS](https://tailwindcss.com/)
|
||
- 🔗 [dyte-io/docs 源代码](https://github.com/dyte-io/docs)
|
||
- 📚 [MDN 文档结构参考](https://developer.mozilla.org/)
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-05-06
|
||
**更新者**: CodeDocs 升级系统
|
||
**版本**: v2.0
|