f8173fd706
refactor(blog): restructure blog post layouts and metadata docs: add markdown migration guide and project rules update style(global.css): update typography theme variables chore: move temp_docs to appropriate blog post locations
213 lines
17 KiB
Markdown
213 lines
17 KiB
Markdown
# 项目说明文档
|
||
|
||
本文档旨在提供对 `zhaoguiyang.site` 项目的全面理解，包括其技术栈、框架、组件库、目录结构等，以便指导 AI 大模型进行代码重构和功能开发。
|
||
|
||
## 1. 项目概述
|
||
|
||
`zhaoguiyang.site` 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能和项目，并包含完整的博客功能，支持多语言（英文和中文）。
|
||
|
||
## 2. 技术栈和框架
|
||
|
||
- **主要框架**: [Astro](https://astro.build/) - 一个用于构建快速、内容驱动的网站的现代前端框架。它允许使用多种 UI 框架（如 React, Vue, Svelte 等）并支持服务器端渲染 (SSR) 和静态站点生成 (SSG)。
|
||
- **UI 框架**: [React](https://react.dev/) - 用于构建用户界面的 JavaScript 库。在本项目中，部分组件（如头部、各个内容区域）是使用 React 实现的，并通过 Astro 的集成功能嵌入到页面中。
|
||
- **样式**: [Tailwind CSS](https://tailwindcss.com/) - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过 `@tailwindcss/vite` 集成到 Astro 项目中。项目还使用了 `@tailwindcss/typography` 插件来美化博客文章内容。
|
||
- **动画**: [Framer Motion](https://www.framer.com/motion/) (`framer-motion`) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在 <mcsymbol name="HeroSection" path="src/components/HeroSection.tsx" filename="HeroSection.tsx" type="function" startline="5"></mcsymbol> 等组件中实现元素的入场动画、悬停效果等。具体使用方式可以参考 <mcfile path="src/components/MotionWrapper.tsx" name="MotionWrapper.tsx"></mcfile> 组件，它是一个统一处理动画逻辑的封装。
|
||
- **图标**: [Lucide React](https://lucide.dev/) - 一个简单、美观的 SVG 图标库。
|
||
- **包管理器**: [pnpm](https://pnpm.io/) - 一个快速、磁盘空间高效的包管理器。
|
||
- **TypeScript**: 用于类型检查和提高代码质量。
|
||
- **国际化**: 使用自定义的国际化解决方案，通过 `src/i18n` 目录下的文件管理多语言内容。
|
||
- **UI 组件增强**: 使用 Radix UI 的 `@radix-ui/react-scroll-area` 和 `@radix-ui/react-slot` 组件来增强用户界面的可访问性和交互性。
|
||
|
||
## 3. 组件库和 UI
|
||
|
||
- **自定义组件**: 项目包含多个自定义 React 组件，位于 `src/components/` 目录下，用于展示不同的内容区域，例如：
|
||
- `HeroSection.tsx`: 个人简介区域。
|
||
- `ExperienceSection.tsx`: 工作经历区域。
|
||
- `SkillsSection.tsx`: 技能展示区域。
|
||
- `ProjectsSection.tsx`: 项目展示区域。
|
||
- `GlassHeader.tsx`: 玻璃拟态效果的导航栏。
|
||
- `Footer.tsx`: 页脚。
|
||
- `LanguageSwitcher.tsx`: 语言切换组件。
|
||
- `ThemeToggle.tsx`: 主题切换组件 (位于 `src/components/ui/`)
|
||
- `AuthorCard.tsx`: 作者信息卡片，用于博客文章页面。
|
||
- `ShareButtons.tsx`: 社交媒体分享按钮组件，用于博客文章页面。
|
||
- `SkillsMarquee.tsx`: 技能标签滚动展示组件，使用 Framer Motion 实现无限滚动效果。
|
||
- **博客组件 (src/components/blog/)**: 专门用于博客功能的组件集合：
|
||
- `BlogList.astro`: 博客文章列表组件，支持分类和标签筛选。
|
||
- `CategoryCard.astro`: 博客分类卡片组件，用于展示和筛选文章分类。
|
||
- `TagCard.astro`: 博客标签卡片组件，用于展示和筛选文章标签。
|
||
- `PostMeta.astro`: 博客文章元数据组件，展示发布日期、阅读时间等信息。
|
||
- **布局组件 (src/components/layout/)**: 用于页面布局的组件：
|
||
- `BlogNavigation.astro`: 博客文章导航组件，用于在文章之间导航。
|
||
- `TableOfContents.astro`: 文章目录组件，自动生成文章内容的目录导航。
|
||
- **UI 组件 (src/components/ui/)**: 基于 Shadcn UI 风格，提供可复用的基础 UI 元素。
|
||
- `button.tsx`: 按钮组件。
|
||
- `card.tsx`: 卡片组件 (包含 `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`)。
|
||
- `glass-card.tsx`: 自定义玻璃拟态效果的卡片组件，使用 Framer Motion。
|
||
- `scroll-area.tsx`: 基于 Radix UI 的滚动区域组件，用于目录导航等场景。
|
||
- `Container.tsx`: 容器组件，用于统一页面内容的宽度和边距。
|
||
- **UI 辅助库**:
|
||
- `class-variance-authority`: 用于创建可变样式的组件。
|
||
- `clsx`: 用于有条件地组合类名。
|
||
- `tailwind-merge`: 用于合并 Tailwind CSS 类名，避免冲突。
|
||
- `tw-animate-css`: 用于集成 Animate.css 的 Tailwind CSS 插件。
|
||
- **Radix UI**: `@radix-ui/react-slot` 和 `@radix-ui/react-scroll-area` 被用作依赖，用于构建可访问和可组合的 UI 组件。
|
||
|
||
## 4. 目录结构
|
||
|
||
```
|
||
├── .gitignore # Git 忽略文件配置
|
||
├── .trae/ # Trae AI 相关配置目录
|
||
│ └── rules/
|
||
│ └── project_rules.md # 本项目说明文档
|
||
├── .vscode/ # VS Code 编辑器配置
|
||
│ ├── extensions.json
|
||
│ └── launch.json
|
||
├── LICENSE # 项目许可证
|
||
├── README.md # 项目自述文件
|
||
├── astro.config.mjs # Astro 配置文件
|
||
├── components.json # Shadcn UI 组件库的配置文件
|
||
├── package.json # 项目依赖和脚本配置
|
||
├── pnpm-lock.yaml # pnpm 锁文件
|
||
├── public/ # 静态资源目录 (如图片、favicon)
|
||
│ ├── favicon.svg
|
||
│ └── profile.jpg
|
||
├── src/
|
||
│ ├── components/ # React 组件目录
|
||
│ │ ├── AuthorCard.tsx # 作者信息卡片组件
|
||
│ │ ├── Footer.tsx # 页脚组件
|
||
│ │ ├── GlassHeader.tsx # 玻璃拟态效果的导航栏
|
||
│ │ ├── LanguageSwitcher.tsx # 语言切换组件
|
||
│ │ ├── MotionWrapper.tsx # Framer Motion 包装组件
|
||
│ │ ├── ShareButtons.tsx # 社交媒体分享按钮组件
|
||
│ │ ├── SkillsMarquee.tsx # 技能标签滚动展示组件
|
||
│ │ ├── blog/ # 博客相关组件
|
||
│ │ │ ├── BlogList.astro # 博客文章列表组件
|
||
│ │ │ ├── CategoryCard.astro # 博客分类卡片组件
|
||
│ │ │ ├── PostMeta.astro # 博客文章元数据组件
|
||
│ │ │ └── TagCard.astro # 博客标签卡片组件
|
||
│ │ ├── layout/ # 布局相关组件
|
||
│ │ │ ├── BlogNavigation.astro # 博客文章导航组件
|
||
│ │ │ └── TableOfContents.astro # 文章目录组件
|
||
│ │ └── ui/ # 通用 UI 组件 (基于 Shadcn UI 风格)
|
||
│ │ ├── button.tsx # 按钮组件
|
||
│ │ ├── card.tsx # 卡片组件
|
||
│ │ ├── glass-card.tsx # 玻璃拟态卡片组件
|
||
│ │ ├── scroll-area.tsx # 滚动区域组件
|
||
│ │ └── theme-toggle.tsx # 主题切换组件
|
||
│ ├── i18n/ # 国际化相关文件
|
||
│ │ ├── ui.ts # 存储翻译文本
|
||
│ │ └── utils.ts # i18n 辅助函数
|
||
│ ├── layouts/ # Astro 布局组件
|
||
│ │ ├── AboutLayout.astro # 关于页面布局
|
||
│ │ ├── BlogLayout.astro # 博客页面布局
|
||
│ │ ├── BlogPostLayout.astro # 博客文章页面布局
|
||
│ │ ├── Layout.astro # 全局页面布局
|
||
│ │ └── TaxonomyPageLayout.astro # 分类/标签页面布局
|
||
│ ├── lib/ # 辅助函数和数据
|
||
│ │ ├── data.ts # 存储个人信息、经历、技能等静态数据
|
||
│ │ └── utils.ts # 通用工具函数
|
||
│ ├── pages/ # Astro 页面组件
|
||
│ │ ├── about.md # 关于页面 (Markdown)
|
||
│ │ ├── blog/ # 博客相关页面
|
||
│ │ │ ├── index.astro # 博客首页
|
||
│ │ │ ├── category/ # 分类页面
|
||
│ │ │ ├── tag/ # 标签页面
|
||
│ │ │ └── posts/ # 博客文章 (Markdown)
|
||
│ │ ├── index.astro # 网站主页 (英文)
|
||
│ │ ├── projects.astro # 项目页面
|
||
│ │ ├── services.md # 服务页面 (Markdown)
|
||
│ │ └── zh/ # 中文语言目录
|
||
│ │ ├── blog/ # 中文博客页面
|
||
│ │ └── index.astro # 网站主页 (中文)
|
||
│ ├── styles/ # 全局样式
|
||
│ │ └── global.css
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ │ └── index.ts # 集中管理项目中的类型定义
|
||
│ └── utils/ # 工具函数
|
||
│ └── blog-utils.ts # 博客相关工具函数
|
||
├── temp_docs/ # 临时文档目录
|
||
└── tsconfig.json # TypeScript 配置文件
|
||
```
|
||
|
||
## 5. 关键文件说明
|
||
|
||
- **`astro.config.mjs`**: 配置 Astro 项目，包括 Vite 插件（如 Tailwind CSS）和 Astro 集成（如 React）。
|
||
- **`package.json`**: 定义项目元数据、依赖项和 npm 脚本（如 `dev`, `build`, `preview`）。
|
||
- **`tsconfig.json`**: 配置 TypeScript 编译器选项，包括路径别名（`@/*` 指向 `./src/*`）和 JSX 设置。
|
||
- **`src/layouts/Layout.astro`**: 定义网站的全局 HTML 结构、头部信息（`<head>`）、全局样式和客户端脚本。所有页面都将使用此布局。
|
||
- **`src/layouts/BlogLayout.astro`**: 博客页面的布局组件，包含博客特有的样式和结构。
|
||
- **`src/layouts/BlogPostLayout.astro`**: 博客文章页面的布局组件，包含文章内容、目录导航、作者信息和分享按钮等。
|
||
- **`src/pages/index.astro`**: 网站的英文版入口页面。它导入并使用 `Layout.astro` 作为布局，并按顺序引入各个 React 内容区域组件。通过 `getLangFromUrl` 从 URL 判断当前语言并传递给布局和组件。`client:only="react"`指令表示这些 React 组件仅在客户端渲染。
|
||
- **`src/pages/zh/index.astro`**: 网站的中文版入口页面，结构与 `index.astro` 类似，但为中文内容服务，展示个人简介、工作经历、技能和项目。
|
||
- **`src/pages/blog/index.astro`**: 博客首页，展示所有博客文章、分类和标签。
|
||
- **`src/lib/data.ts`**: 存储网站展示的静态数据，如个人信息、工作经历、技能列表和项目信息。文件中的许多键值对应于 `src/i18n/ui.ts` 中的翻译键，以支持多语言。这使得内容易于更新和管理，而无需直接修改组件代码。
|
||
- **`src/i18n/ui.ts`**: 定义了支持的语言 (英语和简体中文) 以及所有需要翻译的文本内容的键值对。是实现网站国际化的核心文件。
|
||
- **`src/i18n/utils.ts`**: 包含国际化相关的辅助函数，如 `getLangFromUrl` (从 URL 获取当前语言)、`useTranslations` (提供一个 `t` 函数用于在组件中获取翻译文本) 和 `getLocalizedPath` (生成本地化路径)。
|
||
- **`src/utils/blog-utils.ts`**: 博客功能的工具函数集合，包括获取博客文章、按日期排序、按分类/标签筛选等功能。
|
||
- **`src/types/index.ts`**: 集中管理项目中的类型定义，包括博客文章、作者信息、组件 Props 等接口定义。
|
||
- **`src/components/*.tsx`**: 构成页面主要内容的 React 组件。它们从 `src/lib/data.ts` 获取数据并使用 Tailwind CSS 进行样式设置，使用 Framer Motion 实现动画效果。
|
||
- **`public/`**: 存放可以直接通过 URL 访问的静态文件，如 `favicon.svg` 和 `profile.jpg`。
|
||
|
||
## 6. 数据流和状态管理
|
||
|
||
- **静态数据驱动**：项目主要依赖 `src/lib/data.ts` 中的静态数据来渲染内容。这意味着大部分内容在构建时就已经确定，无需复杂的运行时数据获取或状态管理。
|
||
- **博客内容管理**：博客文章使用 Markdown 文件存储在 `src/pages/blog/posts/` 和 `src/pages/zh/blog/posts/` 目录中，通过 Astro 的 `import.meta.glob` 功能在构建时读取和处理。
|
||
- **无复杂状态管理**：由于项目性质（个人简历/作品集/博客），没有引入 Redux、Zustand 或 React Context 等复杂的状态管理库。组件的状态管理主要通过 React 自身的 `useState` 和 `useEffects` Hook 在组件内部完成，或者通过 props 从父组件传递。
|
||
- **国际化数据流**：`src/i18n/ui.ts` 提供翻译文本，`src/i18n/utils.ts` 提供辅助函数来处理语言切换和文本获取，确保多语言内容正确显示。
|
||
|
||
## 7. 博客功能
|
||
|
||
项目实现了完整的博客功能，主要特点包括：
|
||
|
||
- **Markdown 支持**：使用 Astro 的 Markdown 集成，支持在 Markdown 文件中编写博客文章。
|
||
- **前置元数据**：通过 Markdown 文件的 frontmatter 部分定义文章的标题、描述、发布日期、标签、分类等元数据。
|
||
- **多语言支持**：博客文章支持英文和中文两种语言，分别存储在不同的目录中。
|
||
- **分类和标签**：支持对文章进行分类和添加标签，并提供按分类/标签筛选文章的功能。
|
||
- **文章导航**：在文章页面提供上一篇/下一篇导航功能，方便读者浏览相关内容。
|
||
- **目录导航**：自动生成文章目录，支持点击跳转到对应章节。
|
||
- **作者信息**：在文章页面展示作者信息，包括头像、简介和社交媒体链接。
|
||
- **分享功能**：提供社交媒体分享按钮，方便读者分享文章。
|
||
- **响应式设计**：博客页面适配各种屏幕尺寸，提供良好的移动端体验。
|
||
|
||
## 8. 构建和部署
|
||
|
||
- **构建命令**：项目使用 `pnpm run build` 命令进行构建。此命令会触发 Astro 的构建过程，将项目编译为静态文件，输出到 `dist/` 目录。
|
||
- **开发环境**：使用 `pnpm run dev` 启动开发服务器，支持热重载和实时预览。
|
||
- **预览构建**：使用 `pnpm run preview` 预览构建后的静态文件。
|
||
- **部署**：由于是静态网站，构建产物可以直接部署到任何静态文件托管服务，如 Netlify, Vercel, GitHub Pages 等。
|
||
|
||
## 9. AI 代码重构和功能开发指南
|
||
|
||
在进行代码重构或新功能开发时，请遵循以下原则：
|
||
|
||
- **保持 Astro 核心优势**：优先使用 Astro 的 Islands 架构，确保大部分内容以静态 HTML 形式提供，仅在必要时水合（hydrate）交互式组件。
|
||
- **React 组件化**：对于需要交互的 UI 部分，使用 React 进行组件化开发，并确保组件是可复用和可测试的。
|
||
- **Tailwind CSS 优先**：样式应通过 Tailwind CSS 实用程序类实现。只有在 Tailwind 无法满足需求时，才考虑使用自定义 CSS。
|
||
- **Framer Motion 动画**：所有动画效果通过 Framer Motion 实现，保持动画逻辑的统一性。
|
||
- **国际化支持**：所有用户可见的文本通过 `src/i18n/ui.ts` 进行管理，确保新功能也支持多语言。
|
||
- **数据驱动**：新功能所需的数据集中管理，例如添加到 `src/lib/data.ts` 中，而不是硬编码在组件内部。
|
||
- **性能优化**：关注 Lighthouse 等工具的性能指标，确保代码更改不会引入性能瓶颈。
|
||
- **可访问性**：确保所有 UI 元素都符合 WCAG 标准，特别是对于交互式组件。
|
||
- **代码质量**：遵循 TypeScript 最佳实践，编写清晰、可读、有注释的代码。
|
||
- **测试**：对于复杂逻辑或关键组件，考虑编写单元测试或集成测试。
|
||
- **博客功能扩展**：在扩展博客功能时，保持与现有的文件结构和数据流一致，确保新功能与多语言支持兼容。
|
||
|
||
## 10. 潜在的改进和扩展方向
|
||
|
||
- **CMS 集成**：将静态数据（如项目、博客文章）迁移到 CMS（如 Contentful, Sanity, Strapi），实现更灵活的内容管理。
|
||
- **博客功能增强**：
|
||
- 添加评论系统（如 Disqus, Giscus）
|
||
- 实现文章搜索功能
|
||
- 添加相关文章推荐
|
||
- 支持更多的内容格式（如代码高亮、数学公式）
|
||
- **国际化完善**：除了文本，考虑图片、日期格式等内容的国际化。
|
||
- **性能监控**：集成 Web Vitals 监控，持续跟踪网站性能。
|
||
- **SEO 优化**：进一步优化元标签、结构化数据等，提升搜索引擎排名。
|
||
- **无障碍优化**：深入研究 ARIA 属性和键盘导航，提升无障碍体验。
|
||
- **动画库扩展**：探索 Framer Motion 更多高级特性，或集成其他动画库以实现更丰富的视觉效果。
|
||
- **组件库扩展**：基于 Radix UI 或其他无头 UI 库构建更多可复用的组件。
|
||
- **测试框架引入**：引入 Vitest 或 React Testing Library 等测试框架，提高代码质量和可维护性。
|
||
- **交互式项目展示**：为项目展示部分添加更多交互元素，如项目详情模态框、项目筛选等。
|
||
- **暗色模式优化**：进一步完善暗色模式的视觉效果和用户体验。
|
||
- **性能优化**：实现图片懒加载、代码分割等技术，提升页面加载速度。 |