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
This commit is contained in:
joyzhao
206
docs/markdown-migration-guide.md
Normal file
206
docs/markdown-migration-guide.md
Normal file
@@ -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
|
||||
|
||||
```
|
||||
|
||||
#### 方式二：使用本地图片
|
||||
|
||||
1. 必须将图片文件放在`public/images/blog/`目录下
|
||||
2. 必须在Markdown中使用以下格式引用图片：
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
### 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)`格式
|
||||
- 图片：必须使用``格式
|
||||
- 引用：必须使用`>`标记
|
||||
- 代码：行内代码必须使用单反引号`` ` ``包围，代码块必须使用三反引号包围
|
||||
|
||||
### 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`博客系统的标准流程。所有迁移工作必须严格遵循本文档的规定执行。如有任何问题，请联系项目维护者。
|
||||
Reference in New Issue
Block a user