From f8173fd706afb8a81e78d39d5fce849e8282ad63 Mon Sep 17 00:00:00 2001 From: joyzhao Date: Thu, 19 Jun 2025 20:24:09 +0800 Subject: [PATCH] feat: migrate and organize documentation and blog posts 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 --- .trae/rules/project_rules.md | 120 ++++-- docs/markdown-migration-guide.md | 206 +++++++++++ src/layouts/BlogPostLayout.astro | 25 +- .../posts/browser-rendering-principles.md | 100 +++++ .../posts/docusaurus-v3-with-tailwindcss.md | 129 +++++++ .../zh/blog/posts/git-commit-convention.md | 152 ++++++++ .../gitea-actions-deployment-automation.md | 104 ++++++ .../posts/javascript-map-parseint-trap.md | 86 +++++ src/styles/global.css | 5 + temp_docs/01-03.md | 350 ++++++++++++++++++ temp_docs/05-06.md | 90 +++++ temp_docs/git提交规范.md | 132 +++++++ temp_docs/map遍历数字的陷阱.md | 56 +++ temp_docs/浏览器的运行原理.md | 95 +++++ 14 files changed, 1613 insertions(+), 37 deletions(-) create mode 100644 docs/markdown-migration-guide.md create mode 100644 src/pages/zh/blog/posts/browser-rendering-principles.md create mode 100644 src/pages/zh/blog/posts/docusaurus-v3-with-tailwindcss.md create mode 100644 src/pages/zh/blog/posts/git-commit-convention.md create mode 100644 src/pages/zh/blog/posts/gitea-actions-deployment-automation.md create mode 100644 src/pages/zh/blog/posts/javascript-map-parseint-trap.md create mode 100644 temp_docs/01-03.md create mode 100644 temp_docs/05-06.md create mode 100644 temp_docs/git提交规范.md create mode 100644 temp_docs/map遍历数字的陷阱.md create mode 100644 temp_docs/浏览器的运行原理.md diff --git a/.trae/rules/project_rules.md b/.trae/rules/project_rules.md index 9d865e7..a368e00 100644 --- a/.trae/rules/project_rules.md +++ b/.trae/rules/project_rules.md @@ -4,17 +4,19 @@ ## 1. 项目概述 -`zhaoguiyang.site` 是一个现代化的个人作品集网站模板，具有动画和玻璃拟态效果。该项目旨在展示个人信息、工作经历、技能和项目。 +`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 项目中。 +- **样式**: [Tailwind CSS](https://tailwindcss.com/) - 一个实用工具优先的 CSS 框架，用于快速构建自定义用户界面。通过 `@tailwindcss/vite` 集成到 Astro 项目中。项目还使用了 `@tailwindcss/typography` 插件来美化博客文章内容。 - **动画**: [Framer Motion](https://www.framer.com/motion/) (`framer-motion`) - 一个用于 React 的生产级动画库，用于实现声明式的、基于物理的动画以及复杂的交互动效。在项目中，它被用于增强用户体验，例如在 等组件中实现元素的入场动画、悬停效果等。具体使用方式可以参考 组件，它是一个统一处理动画逻辑的封装。 - **图标**: [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 @@ -27,16 +29,29 @@ - `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` 被用作依赖，用于构建可访问和可组合的 UI 组件。 +- **Radix UI**: `@radix-ui/react-slot` 和 `@radix-ui/react-scroll-area` 被用作依赖，用于构建可访问和可组合的 UI 组件。 ## 4. 目录结构 @@ -59,34 +74,59 @@ │ └── profile.jpg ├── src/ │ ├── components/ # React 组件目录 -│ │ ├── ExperienceSection.tsx -│ │ ├── Footer.tsx -│ │ ├── GlassHeader.tsx -│ │ ├── HeroSection.tsx -│ │ ├── MotionWrapper.tsx # Framer Motion 包装组件 -│ │ ├── ProjectsSection.tsx -│ │ ├── SkillsSection.tsx -│ │ ├── TimelineItem.tsx # 时间轴条目组件 +│ │ ├── AuthorCard.tsx # 作者信息卡片组件 +│ │ ├── Footer.tsx # 页脚组件 +│ │ ├── GlassHeader.tsx # 玻璃拟态效果的导航栏 │ │ ├── LanguageSwitcher.tsx # 语言切换组件 -│ │ └── ui/ # 通用 UI 组件 (基于 Shadcn UI 风格) -│ │ ├── button.tsx # 按钮组件 -│ │ ├── card.tsx # 卡片组件 -│ │ ├── glass-card.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 布局组件 -│ │ └── Layout.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/ # 中文语言目录 -│ │ └── index.astro # 网站主页 (中文) -│ └── styles/ # 全局样式 -│ └── global.css +│ │ ├── blog/ # 中文博客页面 +│ │ └── index.astro # 网站主页 (中文) +│ ├── styles/ # 全局样式 +│ │ └── global.css +│ ├── types/ # TypeScript 类型定义 +│ │ └── index.ts # 集中管理项目中的类型定义 +│ └── utils/ # 工具函数 +│ └── blog-utils.ts # 博客相关工具函数 +├── temp_docs/ # 临时文档目录 └── tsconfig.json # TypeScript 配置文件 ``` @@ -96,26 +136,48 @@ - **`package.json`**: 定义项目元数据、依赖项和 npm 脚本（如 `dev`, `build`, `preview`）。 - **`tsconfig.json`**: 配置 TypeScript 编译器选项，包括路径别名（`@/*` 指向 `./src/*`）和 JSX 设置。 - **`src/layouts/Layout.astro`**: 定义网站的全局 HTML 结构、头部信息（``）、全局样式和客户端脚本。所有页面都将使用此布局。 +- **`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` 中的静态数据来渲染内容。这意味着大部分内容在构建时就已经确定，无需复杂的运行时数据获取或状态管理。 -- **无复杂状态管理**：由于项目性质（个人简历/作品集），没有引入 Redux、Zustand 或 React Context 等复杂的状态管理库。组件的状态管理主要通过 React 自身的 `useState` 和 `useEffects` Hook 在组件内部完成，或者通过 props 从父组件传递。 +- **博客内容管理**：博客文章使用 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. 构建和部署 +## 7. 博客功能 + +项目实现了完整的博客功能，主要特点包括： + +- **Markdown 支持**：使用 Astro 的 Markdown 集成，支持在 Markdown 文件中编写博客文章。 +- **前置元数据**：通过 Markdown 文件的 frontmatter 部分定义文章的标题、描述、发布日期、标签、分类等元数据。 +- **多语言支持**：博客文章支持英文和中文两种语言，分别存储在不同的目录中。 +- **分类和标签**：支持对文章进行分类和添加标签，并提供按分类/标签筛选文章的功能。 +- **文章导航**：在文章页面提供上一篇/下一篇导航功能，方便读者浏览相关内容。 +- **目录导航**：自动生成文章目录，支持点击跳转到对应章节。 +- **作者信息**：在文章页面展示作者信息，包括头像、简介和社交媒体链接。 +- **分享功能**：提供社交媒体分享按钮，方便读者分享文章。 +- **响应式设计**：博客页面适配各种屏幕尺寸，提供良好的移动端体验。 + +## 8. 构建和部署 - **构建命令**：项目使用 `pnpm run build` 命令进行构建。此命令会触发 Astro 的构建过程，将项目编译为静态文件，输出到 `dist/` 目录。 +- **开发环境**：使用 `pnpm run dev` 启动开发服务器，支持热重载和实时预览。 +- **预览构建**：使用 `pnpm run preview` 预览构建后的静态文件。 - **部署**：由于是静态网站，构建产物可以直接部署到任何静态文件托管服务，如 Netlify, Vercel, GitHub Pages 等。 -## 8. AI 代码重构和功能开发指南 +## 9. AI 代码重构和功能开发指南 在进行代码重构或新功能开发时，请遵循以下原则： @@ -129,15 +191,23 @@ - **可访问性**：确保所有 UI 元素都符合 WCAG 标准，特别是对于交互式组件。 - **代码质量**：遵循 TypeScript 最佳实践，编写清晰、可读、有注释的代码。 - **测试**：对于复杂逻辑或关键组件，考虑编写单元测试或集成测试。 +- **博客功能扩展**：在扩展博客功能时，保持与现有的文件结构和数据流一致，确保新功能与多语言支持兼容。 -## 9. 潜在的改进和扩展方向 +## 10. 潜在的改进和扩展方向 - **CMS 集成**：将静态数据（如项目、博客文章）迁移到 CMS（如 Contentful, Sanity, Strapi），实现更灵活的内容管理。 -- **博客功能**：添加一个简单的博客模块，用于发布文章。 +- **博客功能增强**： + - 添加评论系统（如 Disqus, Giscus） + - 实现文章搜索功能 + - 添加相关文章推荐 + - 支持更多的内容格式（如代码高亮、数学公式） - **国际化完善**：除了文本，考虑图片、日期格式等内容的国际化。 - **性能监控**：集成 Web Vitals 监控，持续跟踪网站性能。 - **SEO 优化**：进一步优化元标签、结构化数据等，提升搜索引擎排名。 - **无障碍优化**：深入研究 ARIA 属性和键盘导航，提升无障碍体验。 - **动画库扩展**：探索 Framer Motion 更多高级特性，或集成其他动画库以实现更丰富的视觉效果。 - **组件库扩展**：基于 Radix UI 或其他无头 UI 库构建更多可复用的组件。 -- **测试框架引入**：引入 Vitest 或 React Testing Library 等测试框架，提高代码质量和可维护性。 \ No newline at end of file +- **测试框架引入**：引入 Vitest 或 React Testing Library 等测试框架，提高代码质量和可维护性。 +- **交互式项目展示**：为项目展示部分添加更多交互元素，如项目详情模态框、项目筛选等。 +- **暗色模式优化**：进一步完善暗色模式的视觉效果和用户体验。 +- **性能优化**：实现图片懒加载、代码分割等技术，提升页面加载速度。 \ No newline at end of file diff --git a/docs/markdown-migration-guide.md b/docs/markdown-migration-guide.md new file mode 100644 index 0000000..3cc1edc --- /dev/null +++ b/docs/markdown-migration-guide.md @@ -0,0 +1,206 @@ +# Markdown博客文章迁移指南 + +本文档规定了将Markdown文档迁移到`zhaoguiyang.site`博客系统的标准流程和必要步骤。所有迁移工作必须严格按照本指南执行。 + +## 1. 博客文章结构 + +在`zhaoguiyang.site`项目中，博客文章按照语言分别存储在以下目录： + +- 英文文章：`/src/pages/blog/posts/` +- 中文文章：`/src/pages/zh/blog/posts/` + +## 2. 文件命名规范 + +为了保持一致性和良好的URL结构，请遵循以下命名规范： + +- 使用小写字母 +- 单词之间使用连字符（`-`）分隔 +- 文件名应简洁地反映文章内容 +- 使用`.md`扩展名 + +示例：`react-performance-optimization.md` + +## 3. 前置元数据（Frontmatter）要求 + +每篇博客文章必须在文件顶部包含YAML格式的前置元数据，用三个连字符（`---`）包围。 + +### 必需属性 + +```yaml +--- +title: "文章标题" # 文章标题（必需） +description: "文章描述" # 文章简短描述或摘要（必需） +date: "2023-06-15" # 发布日期，格式：YYYY-MM-DD（必需） +image: "图片URL" # 文章封面图片URL（必需） +tags: ["标签1", "标签2"] # 文章标签（必需） +tagId: ["tag1", "tag2"] # 标签唯一标识符（必需） +category: "文章分类" # 文章分类（必需） +categoryId: "category-id" # 分类唯一标识符（必需） +readTime: "5 min read" # 阅读时间（必需） +--- +``` + +### 前置元数据示例 + +```yaml +--- +title: "React性能优化最佳实践" +description: "本文探讨了提升React应用性能的多种策略和技术，包括组件优化、状态管理和渲染优化。" +date: "2023-06-15" +image: "https://example.com/images/react-performance.jpg" +tags: ["React", "性能优化", "前端开发"] +tagId: ["react", "performance", "frontend"] +category: "前端开发" +categoryId: "frontend" +readTime: "5 min read" +--- +``` + +### 属性说明 + +| 属性 | 类型 | 描述 | 是否必需 | +|------|------|------|----------| +| `title` | 字符串 | 文章标题 | 是 | +| `description` | 字符串 | 文章描述/摘要 | 是 | +| `date` | 字符串 | 发布日期（YYYY-MM-DD格式） | 是 | +| `image` | 字符串 | 文章封面图片URL | 是 | +| `tags` | 字符串数组 | 文章标签 | 是 | +| `tagId` | 字符串数组 | 标签唯一标识符（用于多语言环境） | 是 | +| `category` | 字符串 | 文章分类 | 是 | +| `categoryId` | 字符串 | 分类唯一标识符（用于多语言环境） | 是 | +| `readTime` | 字符串 | 阅读时间（如"5 min read"） | 是 | + +## 4. 迁移步骤 + +### 4.1 准备Markdown文件 + +1. 检查并确认Markdown文件的格式和内容符合项目规范 +2. 文件必须使用UTF-8编码 +3. 必须移除所有不兼容的HTML标签和特殊格式 + +### 4.2 添加前置元数据 + +1. 在文件顶部添加前置元数据区域（用`---`包围） +2. 填写所有必需属性（`title`、`description`、`date`、`image`、`tags`、`tagId`、`category`、`categoryId`、`readTime`） +3. 确保所有属性都按照规定格式填写完整 + +### 4.3 图片处理 + +文章中的图片必须按照以下两种方式之一进行处理： + +#### 方式一：使用外部图片链接 + +必须在Markdown中使用完整的URL： + +```markdown +![图片描述](https://example.com/path/to/image.jpg) +``` + +#### 方式二：使用本地图片 + +1. 必须将图片文件放在`public/images/blog/`目录下 +2. 必须在Markdown中使用以下格式引用图片： + +```markdown +![图片描述](/images/blog/image.jpg) +``` + +### 4.4 放置文件 + +必须根据文章语言，将处理好的Markdown文件放在指定目录： + +- 英文文章：必须放在`/src/pages/blog/posts/your-article-name.md` +- 中文文章：必须放在`/src/pages/zh/blog/posts/your-article-name.md` + +### 4.5 验证 + +1. 必须通过以下命令启动开发服务器：`pnpm run dev` +2. 必须访问博客页面，确认文章显示正常 +3. 必须检查文章内容、元数据、图片和格式是否完全符合规范 + +## 5. Markdown语法支持 + +本博客系统仅支持以下Markdown语法： + +### 5.1 基本语法 + +- 标题：必须使用`#`、`##`、`###`等标记，一级标题`#`仅用于文章标题 +- 强调：必须使用`*斜体*`表示斜体，`**粗体**`表示粗体 +- 列表：必须使用`-`或`1.`分别表示无序和有序列表 +- 链接：必须使用`[链接文本](URL)`格式 +- 图片：必须使用`![替代文本](图片URL)`格式 +- 引用：必须使用`>`标记 +- 代码：行内代码必须使用单反引号`` ` ``包围，代码块必须使用三反引号包围 + +### 5.2 代码块 + +必须使用三个反引号（```）包围代码，并明确指定语言以启用语法高亮： + +````markdown +```javascript +function greeting() { + console.log("Hello, world!"); +} +``` +```` + +### 5.3 表格 + +表格必须使用以下格式： + +```markdown +| 列1 | 列2 | 列3 | +|-----|-----|-----| +| 内容1 | 内容2 | 内容3 | +| 内容4 | 内容5 | 内容6 | +``` + +## 6. 多语言内容管理 + +本项目必须同时提供英文和中文两个版本的文章，遵循以下规则： + +1. 创建两个版本的Markdown文件（内容对应但语言不同） +2. 两个文件必须使用完全相同的`tagId`和`categoryId`值 +3. 两个文件必须使用相同的文件名，但放置在不同的语言目录中 +4. 英文版文章必须放在`/src/pages/blog/posts/`目录 +5. 中文版文章必须放在`/src/pages/zh/blog/posts/`目录 + +文章对应示例： + +- 英文版：`/src/pages/blog/posts/react-performance-tips.md` +- 中文版：`/src/pages/zh/blog/posts/react-performance-tips.md` + +两个版本的文章必须保持同步更新，确保内容的一致性。 + +### 6.1 文档翻译规则 + +处理文档翻译时必须遵循以下规则： + +1. 如果只有中文版文档，必须将其翻译为专业的英文版 +2. 如果只有英文版文档，必须将其翻译为专业的中文版 +3. 如果同时存在中英文两个版本，无需翻译，直接将文件放置到对应的语言目录中 +4. 对于必需的前置元数据属性： + - 如果原始Markdown文件中已存在该属性，必须直接使用原有内容 + - 如果原始Markdown文件中缺少某些必需属性，必须根据文档内容自动生成合适的属性值 + - 生成的属性必须与文章内容高度相关，不得使用通用或无关的内容 + +## 7. 注意事项 + +- **图片大小**：必须优化所有图片大小，图片文件大小不得超过500KB +- **内容格式**：必须使用正确的标题层级（从h2开始）和段落分隔 +- **代码示例**：所有代码示例必须使用正确的语法高亮标记 +- **内部链接**：必须使用相对路径链接到网站内的其他页面 +- **外部链接**：必须对所有外部链接使用完整URL，并添加`target="_blank"`属性 + +## 8. 故障排除 + +迁移过程中出现问题时，必须按以下顺序检查： + +1. 前置元数据格式必须完全符合YAML语法规范 +2. 文件编码必须为UTF-8，不允许使用其他编码 +3. 文件路径和名称必须完全符合命名规范 +4. Markdown语法必须正确无误 + +--- + +本指南是将Markdown文档迁移到`zhaoguiyang.site`博客系统的标准流程。所有迁移工作必须严格遵循本文档的规定执行。如有任何问题，请联系项目维护者。 \ No newline at end of file diff --git a/src/layouts/BlogPostLayout.astro b/src/layouts/BlogPostLayout.astro index e3074bc..69c8cbf 100644 --- a/src/layouts/BlogPostLayout.astro +++ b/src/layouts/BlogPostLayout.astro @@ -50,6 +50,17 @@ const finalReadingTime = readTime ? parseInt(readTime.replace(/\D/g, '')) : unde
+ +

{title}

@@ -59,21 +70,11 @@ const finalReadingTime = readTime ? parseInt(readTime.replace(/\D/g, '')) : unde {description}

)} - -
-
+
diff --git a/src/pages/zh/blog/posts/browser-rendering-principles.md b/src/pages/zh/blog/posts/browser-rendering-principles.md new file mode 100644 index 0000000..9f87f46 --- /dev/null +++ b/src/pages/zh/blog/posts/browser-rendering-principles.md @@ -0,0 +1,100 @@ +--- +layout: "@/layouts/BlogPostLayout.astro" +title: "浏览器的运行原理" +description: "本文详细介绍了浏览器渲染页面的七个阶段（HTML解析、样式计算、布局、分层、绘制、分块、光栅化）以及reflow（回流）、repaint（重绘）的概念和transform效率高的原因。" +date: "2023-08-10" +image: "https://images.unsplash.com/photo-1510511459019-5dda7724fd87?q=80&w=1470&auto=format&fit=crop" +tags: ["浏览器", "前端", "渲染原理"] +tagId: ["browser", "frontend", "rendering"] +category: "前端开发" +categoryId: "frontend" +readTime: "7 min read" +--- + +浏览器渲染页面的过程可以分为七个阶段： + +### 1. HTML解析 + +浏览器接收到服务器响应的HTML文档后，会首先解析HTML文档，构建DOM树。DOM树是由DOM元素及属性节点组成的，树的根是document对象。 + +### 2. 样式计算 + +浏览器会解析CSS文件和元素上的inline样式，计算出DOM节点的样式。这个过程包括： + +- 把CSS转换为浏览器能够理解的结构 +- 计算出DOM节点的具体样式 + +### 3. 布局 + +布局阶段会计算出DOM树中可见元素的几何位置，这个过程叫做布局或重排。 + +### 4. 分层 + +浏览器会根据布局后的DOM树，将其分为多个图层。这个过程主要是为了处理页面中的复杂效果，如3D变换、页面滚动等。 + +### 5. 绘制 + +在分层的基础上，浏览器会为每个图层生成绘制列表，并将其提交到合成线程。 + +### 6. 分块 + +合成线程会将图层划分为图块，这些图块的大小通常是256x256或者512x512。 + +### 7. 光栅化 + +合成线程会按照视口附近的图块来优先生成位图，这个过程叫做光栅化。光栅化过程中，会将图块转换为位图。 + +## 回流（Reflow）和重绘（Repaint） + +### 回流（Reflow） + +当我们对DOM的修改引发了DOM几何尺寸的变化（比如修改元素的宽、高或隐藏元素等）时，浏览器需要重新计算元素的几何属性，然后再将计算的结果绘制出来。这个过程就是回流（也叫重排）。 + +引起回流的操作包括： + +- 页面首次渲染 +- 浏览器窗口大小发生改变 +- 元素尺寸或位置发生改变 +- 元素内容变化（文字数量或图片大小等等） +- 元素字体大小变化 +- 添加或者删除可见的DOM元素 +- 激活CSS伪类（例如：:hover） +- 查询某些属性或调用某些方法 + +一些常用且会导致回流的属性和方法： + +- clientWidth、clientHeight、clientTop、clientLeft +- offsetWidth、offsetHeight、offsetTop、offsetLeft +- scrollWidth、scrollHeight、scrollTop、scrollLeft +- scrollIntoView()、scrollIntoViewIfNeeded() +- getComputedStyle() +- getBoundingClientRect() +- scrollTo() + +### 重绘（Repaint） + +当我们对DOM的修改导致了样式的变化、但未影响其几何属性（比如修改了颜色或背景色）时，浏览器不需要重新计算元素的几何属性、直接为该元素绘制新的样式。这个过程叫做重绘。 + +相比回流，重绘的性能开销较小，因为重绘只是重新绘制元素的外观，而不需要重新计算元素的位置。 + +## 为什么transform效率高 + +transform是通过创建一个新的复合图层来实现的，这个复合图层会单独进行绘制，然后再与其他图层进行合成。这样，当我们使用transform进行变换时，只需要重新绘制这个复合图层，而不需要重新绘制整个页面。 + +使用transform可以避免回流和重绘，因为它不会影响到DOM的布局，只会影响到最终的渲染结果。这就是为什么使用transform进行动画会比直接修改元素的top、left等属性效率高的原因。 + +## 优化策略 + +为了减少回流和重绘，我们可以采取以下策略： + +1. **批量修改DOM**：使用DocumentFragment或者先将元素设为display: none，然后进行多次修改，最后再显示。 + +2. **避免频繁读取会引发回流/重绘的属性**：如果必须多次读取，就将值缓存起来。 + +3. **使用transform和opacity来实现动画效果**：这两个属性不会触发回流。 + +4. **使用will-change属性**：这个属性可以提前告知浏览器元素将要发生的变化，浏览器可以提前做好优化工作。 + +5. **使用绝对定位或固定定位**：绝对定位和固定定位的元素发生变化时，只会影响自身，不会影响其他元素。 + +通过理解浏览器的渲染原理和优化策略，我们可以编写出更高效的前端代码，提升用户体验。 \ No newline at end of file diff --git a/src/pages/zh/blog/posts/docusaurus-v3-with-tailwindcss.md b/src/pages/zh/blog/posts/docusaurus-v3-with-tailwindcss.md new file mode 100644 index 0000000..c673e08 --- /dev/null +++ b/src/pages/zh/blog/posts/docusaurus-v3-with-tailwindcss.md @@ -0,0 +1,129 @@ +--- +layout: "@/layouts/BlogPostLayout.astro" +title: "Docusaurus v3中使用Tailwind CSS的样式" +description: "本文详细介绍了如何在Docusaurus v3中集成和配置Tailwind CSS，包括安装依赖、配置tailwind.config.js、创建tailwind.css和postcss.config.js等步骤。" +date: "2023-11-05" +image: "https://images.unsplash.com/photo-1555066931-4365d14bab8c?q=80&w=1470&auto=format&fit=crop" +tags: ["Docusaurus", "TailwindCSS", "前端框架"] +tagId: ["docusaurus", "tailwindcss", "frontend-framework"] +category: "前端开发" +categoryId: "frontend" +readTime: "4 min read" +--- + +## 安装相关依赖 + +```bash +npm install tailwindcss +``` +## 配置tailwind.config.js + +```js +/** @type {import('tailwindcss').Config} */ +module.exports = { + content: [ + "./src/**/*.{js,jsx,ts,tsx,md,mdx}", + "./docs/**/*.{md,mdx}", + ], + theme: { + screens: { + xs: '480px', + sm: '576px', + md: '768px', + lg: '998px', + xl: '1200px', + '2xl': '1400px', + }, + extend: { + fontFamily: { + sans: 'var(--ifm-font-family-base)', + firacode: 'var(--font-family-firacode)', + kaiti: 'var(--font-family-kaiti)', + }, + colors: { + 'font-color': 'var(--ifm-font-color-base)', + 'link-color': 'var(--ifm-link-color)', + 'link-hover-color': 'var(--ifm-link-hover-color)', + primary: 'var(--ifm-color-primary)', + 'primary-light': 'var(--ifm-color-primary-light)', + 'primary-lighter': 'var(--ifm-color-primary-lighter)', + 'primary-lightest': 'var(--ifm-color-primary-lightest)', + 'primary-dark': 'var(--ifm-color-primary-dark)', + 'primary-darker': 'var(--ifm-color-primary-darker)', + 'primary-darkest': 'var(--ifm-color-primary-darkest)', + }, + boxShadow: { + nysm: '0 0 2px 0 rgb(0 0 0 / 0.05)', + ny: '0 0 3px 0 rgb(0 0 0 / 0.1), 0 0 2px - 1px rgb(0 0 0 / 0.1)', + nymd: '0 0 6px -1px rgb(0 0 0 / 0.1), 0 0 4px -2px rgb(0 0 0 / 0.1)', + nylg: '0 0 15px -3px rgb(0 0 0 / 0.1), 0 0 6px -4px rgb(0 0 0 / 0.1)', + spread: '0 5px 40px rgb(0 0 0 / 0.1)', + }, + }, + }, + plugins: [], + darkMode: ["class", '[data-theme="dark"]'], + corePlugins: { + preflight: false, + }, + blocklist: ["container"], +} +``` +## 创建tailwind.css + +在`src/css`目录下创建`tailwind.css`文件，并写入以下内容： + +```css +@tailwind base; +@tailwind components; +@tailwind utilities; +``` +**注意：创建完成后是需要在custom.css中导入tailwind.css的，否则tailwind样式不会生效** + +## 创建postcss.config.js + +在项目根目录下创建`postcss.config.js`文件，并写入以下内容： + +```js +module.exports = { + plugins: { + tailwindcss: {}, + autoprefixer: {}, + } +} +``` + +## 在custom.css中导入tailwind.css + +找到项目中的`src/css/custom.css`文件，在文件顶部添加以下内容： + +```css +@import './tailwind.css'; +``` + +## 使用Tailwind CSS + +现在，你可以在项目中使用Tailwind CSS的样式了。例如： + +```jsx +
+

Hello Tailwind CSS

+

This is a paragraph styled with Tailwind CSS

+
+``` + +## 注意事项 + +1. 由于Docusaurus已经有自己的CSS样式，所以我们在配置Tailwind CSS时禁用了`preflight`，这样可以避免样式冲突。 + +2. 我们使用了`darkMode: ["class", '[data-theme="dark"]']`配置，这样可以让Tailwind CSS的暗黑模式与Docusaurus的暗黑模式保持一致。 + +3. 我们在`theme.extend.colors`中添加了一些变量，这些变量使用了Docusaurus的CSS变量，这样可以让Tailwind CSS的颜色与Docusaurus的主题颜色保持一致。 + +4. 我们在`blocklist`中添加了`container`，这是因为Docusaurus已经有自己的容器样式，我们不希望Tailwind CSS的容器样式覆盖它。 + +## 总结 + +通过以上步骤，我们成功地在Docusaurus v3中集成了Tailwind CSS。现在，我们可以使用Tailwind CSS的所有功能，同时保持与Docusaurus主题的一致性。 + +希望这篇文章对你有所帮助！如果你有任何问题，欢迎在评论区留言。 \ No newline at end of file diff --git a/src/pages/zh/blog/posts/git-commit-convention.md b/src/pages/zh/blog/posts/git-commit-convention.md new file mode 100644 index 0000000..ce93da8 --- /dev/null +++ b/src/pages/zh/blog/posts/git-commit-convention.md @@ -0,0 +1,152 @@ +--- +layout: "@/layouts/BlogPostLayout.astro" +title: "Git提交规范" +description: "本文详细介绍了Git提交规范，包括Header、Body和Footer三个部分的具体内容和使用规则，帮助团队成员更好地理解和遵循统一的提交标准。" +date: "2023-10-20" +image: "https://images.unsplash.com/photo-1618401471353-b98afee0b2eb?q=80&w=1476&auto=format&fit=crop" +tags: ["Git", "规范", "版本控制"] +tagId: ["git", "convention", "version-control"] +category: "开发工具" +categoryId: "dev-tools" +readTime: "5 min read" +--- + +### 为什么需要提交规范 + +在团队协作中，如果Git的提交说明精准，在后期协作以及Bug处理时会变得有据可查，项目的开发可以根据规范的提交说明快速生成开发日志，从而方便开发者或用户追踪项目的开发信息和功能特性。 + +### 提交说明的结构 + +提交说明包含三个部分：Header、Body 和 Footer。 + +``` +
+ + + +