zhaoguiyang.site/docs/markdown-migration-guide.md

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格式的前置元数据，用三个连字符（---）包围。

必需属性

---
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" # 阅读时间（必需）
---

前置元数据示例

---
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：

![图片描述](https://example.com/path/to/image.jpg)

方式二：使用本地图片

1. 必须将图片文件放在public/images/blog/目录下
2. 必须在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 代码块

必须使用三个反引号（```）包围代码，并明确指定语言以启用语法高亮：

```javascript
function greeting() {
  console.log("Hello, world!");
}
```

5.3 表格

表格必须使用以下格式：

| 列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博客系统的标准流程。所有迁移工作必须严格遵循本文档的规定执行。如有任何问题，请联系项目维护者。