分离blog和docs的布局

2025-08-07 15:52:23 +08:00
parent df43c1845e
commit bf0add6dc6
8 changed files with 581 additions and 1 deletions
--- a/项目说明/简介文档.md
+++ b/项目说明/简介文档.md
@@ -0,0 +1,228 @@
+# Estel Docs 文档系统 - 项目简介
+
+## 📋 项目概述
+
+**Estel Docs** 是一个基于 Nuxt 4 构建的现代化文档系统，采用简约设计但功能强大。系统支持文档管理和博客发布，提供完整的 Markdown 内容管理解决方案。
+
+## 🏗️ 技术架构
+
+### 核心技术栈
+- **框架**: Nuxt 4 (Vue 3 + Vite)
+- **UI 组件库**: Nuxt UI Pro
+- **内容管理**: Nuxt Content 3
+- **图片优化**: Nuxt Image
+- **图标系统**: Lucide + Iconify
+- **类型安全**: TypeScript
+- **包管理**: pnpm
+- **代码规范**: ESLint
+
+### 主要模块
+```typescript
+modules: [
+  '@nuxt/eslint',      // 代码规范
+  '@nuxt/image',        // 图片优化
+  '@nuxt/ui-pro',       // UI 组件库
+  '@nuxt/content',      // 内容管理
+  'nuxt-og-image',      // Open Graph 图片生成
+  '@nuxt/fonts',        // 字体优化
+  'nuxt-llms'          // AI 集成
+]
+```
+
+## 📁 项目结构
+
+```
+项目根目录/
+├── app/                    # 应用核心代码
+│   ├── components/         # Vue 组件
+│   │   ├── blog/          # 博客相关组件
+│   │   ├── docs/          # 文档相关组件
+│   │   └── shared/        # 共享组件
+│   ├── layouts/           # 布局组件
+│   │   ├── blog.vue       # 博客布局
+│   │   └── docs.vue       # 文档布局
+│   ├── pages/             # 页面路由
+│   └── composables/       # 组合式函数
+├── content/               # 内容目录
+│   ├── docs/             # 文档内容
+│   │   ├── 1.简单文档/
+│   │   └── 2.无人自助系统/
+│   └── blog/             # 博客内容
+│       ├── 1.技术栈/
+│       ├── 2.AI/
+│       └── 3.生活/
+├── public/               # 静态资源
+└── nuxt.config.ts       # Nuxt 配置
+```
+
+## 🎯 核心功能
+
+### 1. 文档系统 (Docs)
+- **Markdown 支持**: 完整的 Markdown 语法支持
+- **目录导航**: 自动生成文档目录结构
+- **搜索功能**: 全文搜索和导航搜索
+- **代码高亮**: 语法高亮和代码块
+- **响应式设计**: 适配各种设备屏幕
+- **深色模式**: 支持明暗主题切换
+
+### 2. 博客系统 (Blog)
+- **文章列表**: 响应式卡片布局展示
+- **图片预览**: 支持文章封面图片
+- **分类管理**: 按技术栈、AI、生活等分类
+- **时间显示**: 文章发布时间展示
+- **原始内容查看**: 支持查看 Markdown 原始内容
+
+### 3. 内容管理
+- **双集合架构**: docs 和 blog 两个独立内容集合
+- **Schema 验证**: 使用 Zod 进行内容结构验证
+- **导航配置**: 支持 .navigation.yml 文件配置
+- **SEO 优化**: 自动生成 Open Graph 图片
+
+## 🎨 前端样式与呈现
+
+### 设计理念
+- **简约现代**: 采用简洁的设计语言
+- **响应式优先**: 移动端优先的响应式设计
+- **可访问性**: 遵循 WCAG 可访问性标准
+- **性能优化**: 图片懒加载、代码分割等
+
+### 主要样式特点
+1. **卡片式布局**: 博客文章采用卡片式展示
+2. **渐变效果**: Hero 区域使用渐变背景
+3. **悬停动画**: 丰富的交互动画效果
+4. **圆角设计**: 统一的圆角设计语言
+5. **阴影层次**: 合理的阴影层次营造深度感
+
+### 组件系统
+- **BlogHero**: 博客首页 Hero 区域
+- **BlogHeader**: 博客页面头部导航
+- **IndexBlog**: 博客文章列表组件
+- **AppSidebar**: 侧边栏导航组件
+- **AppHeader**: 顶部导航组件
+
+## 🔧 实现方式
+
+### 1. 内容管理实现
+```typescript
+// content.config.ts
+collections: {
+  docs: defineCollection({
+    type: 'page',
+    source: { include: 'docs/**' },
+    schema: z.object({
+      rawbody: z.string(),
+      links: z.array(z.object({
+        label: z.string(),
+        icon: z.string(),
+        to: z.string()
+      })).optional()
+    })
+  }),
+  blog: defineCollection({
+    type: 'page',
+    source: { include: 'blog/**' },
+    schema: z.object({
+      rawbody: z.string(),
+      img: z.string(),
+      date: z.string()
+    })
+  })
+}
+```
+
+### 2. 路由系统
+- **动态路由**: `[...slug].vue` 处理所有内容页面
+- **布局切换**: 根据路径自动选择 docs 或 blog 布局
+- **原始内容**: `/raw/[...slug]` 查看 Markdown 原始内容
+
+### 3. 数据查询
+```typescript
+// 查询文档内容
+const { data: page } = await useAsyncData(
+  `page-${route.path}`,
+  () => queryCollection('docs').path(queryPath.value).first()
+)
+
+// 查询博客文章
+const { data: articles } = await useAsyncData(
+  'blog-articles',
+  () => queryCollection('blog')
+    .select('path', 'title', 'description', 'img', 'date')
+    .where('path', 'NOT LIKE', '%navigation%')
+    .all()
+)
+```
+
+## ⚠️ 注意事项
+
+### 1. 开发环境
+- **Node.js 版本**: 建议使用 Node.js 18+
+- **包管理器**: 使用 pnpm 作为包管理器
+- **TypeScript**: 严格模式，注意类型安全
+
+### 2. 内容管理
+- **文件命名**: 使用数字前缀确保排序 (如: `1.技术栈/`)
+- **导航配置**: 在目录下创建 `.navigation.yml` 配置导航
+- **图片路径**: 使用相对路径或外部 CDN 链接
+
+### 3. 部署相关
+- **静态生成**: 支持静态站点生成 (SSG)
+- **服务端渲染**: 支持服务端渲染 (SSR)
+- **环境变量**: 注意配置必要的环境变量
+
+### 4. 性能优化
+- **图片优化**: 使用 Nuxt Image 进行图片优化
+- **代码分割**: 自动代码分割和懒加载
+- **缓存策略**: 合理配置缓存策略
+
+## 🚀 还需要什么
+
+### 1. 功能增强
+- [ ] **评论系统**: 集成评论功能
+- [ ] **用户认证**: 添加用户登录注册
+- [ ] **内容编辑**: 在线 Markdown 编辑器
+- [ ] **版本控制**: 内容版本管理
+- [ ] **多语言**: 国际化支持
+
+### 2. 性能优化
+- [ ] **CDN 配置**: 配置 CDN 加速
+- [ ] **缓存策略**: 优化缓存配置
+- [ ] **图片压缩**: 自动图片压缩
+- [ ] **代码分割**: 进一步优化代码分割
+
+### 3. 开发工具
+- [ ] **自动化测试**: 添加单元测试和集成测试
+- [ ] **CI/CD**: 配置自动化部署流程
+- [ ] **监控系统**: 添加性能监控
+- [ ] **错误追踪**: 集成错误追踪系统
+
+### 4. 内容管理
+- [ ] **内容备份**: 自动内容备份策略
+- [ ] **SEO 优化**: 进一步优化 SEO
+- [ ] **搜索增强**: 改进搜索功能
+- [ ] **内容导入**: 支持批量内容导入
+
+### 5. 用户体验
+- [ ] **PWA 支持**: 添加 PWA 功能
+- [ ] **离线支持**: 离线内容访问
+- [ ] **阅读模式**: 专注阅读模式
+- [ ] **分享功能**: 社交媒体分享
+
+## 📊 技术指标
+
+- **构建时间**: < 30s
+- **首屏加载**: < 2s
+- **Lighthouse 评分**: > 90
+- **SEO 评分**: > 95
+- **可访问性**: > 90
+
+## 🔗 相关链接
+
+- **项目仓库**: https://github.com/estel-li/estel-docs
+- **在线演示**: https://docs.jiwei.xin
+- **个人博客**: https://lijue.me
+- **技术文档**: https://nuxt.com/docs
+
+---
+
+*最后更新: 2024年12月*